RFC 4730
A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML)
4. Event Package Formal Definition
4.1. Event Package Name
This document defines a SIP Event Package as defined in RFC 3265 [5]. The event-package token name for this package is: "kpml"4.2. Event Package Parameters
This package defines three Event Package parameters: call-id, remote- tag, and local-tag. These parameters MUST be present, to identify the subscription dialog. The User Interface matches the local-tag against the to tag, the remote-tag against the from tag, and the call-id against the Call-ID. The ABNF for these parameters is below. It refers to many constructions from the ABNF of RFC 3261, such as EQUAL, DQUOTE, and token. call-id = "call-id" EQUAL ( token / DQUOTE callid DQUOTE ) ;; NOTE: any DQUOTEs inside callid MUST be escaped! remote-tag = "remote-tag" EQUAL token local-tag = "local-tag" EQUAL token
If any call-ids contain embedded double-quotes, those double-quotes MUST be escaped using the backslash-quoting mechanism. Note that the call-id parameter may need to be expressed as a quoted string. This is because the ABNF for the callid production and the word production, which is used by callid (both from RFC 3261 [1]), allow some characters (such as "@", "[", and ":") that are not allowed within a token.4.3. SUBSCRIBE Bodies
Applications using this event package include an application/ kpml-request+xml body in SUBSCRIBE requests to indicate which digit patterns they are interested in. The syntax of this body type is formally described in Section 5.2.4.4. Subscription Duration
The subscription lifetime should be longer than the expected call time. Subscriptions to this event package MAY range from minutes to weeks. Subscriptions in hours or days are more typical and are RECOMMENDED. The default subscription duration for this event package is 7200 seconds. Subscribers MUST be able to handle the User Interface returning an Expires value smaller than the requested value. Per RFC 3265 [5], the subscription duration is the value returned by the Notifier in the 200 OK Expires header.4.5. NOTIFY Bodies
NOTIFY requests can contain application/kpml-response+xml (KPML Response) bodies. The syntax of this body type is formally described in Section 5.3. NOTIFY requests in immediate response to a SUBSCRIBE request MUST NOT contain a body unless they are notifying the subscriber of an error condition or previously buffered digits. Notifiers MAY send notifications with any format acceptable to the subscriber (based on the subscriber's inclusion of these formats in an Accept header). A future extension MAY define other NOTIFY bodies. If no "Accept" header is present in the SUBSCRIBE, the body type defined in this document MUST be assumed.4.6. Subscriber Generation of SUBSCRIBE Requests
A kpml request document contains a <pattern> element with a series of <regex> tags. Each <regex> element specifies a potential pattern for the User Interface to match. Section 5.1 describes the DRegex, or digit regular expression, language.
KPML specifies key press event notification filters. The MIME type for KPML requests is application/kpml-request+xml. The KPML request document MUST be well formed and SHOULD be valid. KPML documents MUST conform to XML 1.0 [14] and MUST use UTF-8 encoding. Because of the potentially sensitive nature of the information reported by KPML, subscribers SHOULD use sips: and MAY use S/MIME on the content. Subscribers MUST be prepared for the notifier to insist on authentication of the subscription request. Subscribers MUST be prepared for the notifier to insist on using a secure communication channel.4.7. 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 User Interface (notifier) MUST authenticate the requesting party in some way before accepting the subscription. User Interfaces MUST implement SIP Digest authentication as required by RFC 3261 [4] and MUST implement the sips: scheme and TLS. Upon authenticating the requesting party, the User Interface determines if the requesting party has authorization to monitor the user's key presses. The default authorization policy is to allow a KPML subscriber who can authenticate with a specific identity to monitor key presses from SIP sessions in which the same or equivalent authenticated identity is a participant. In addition, KPML will often be used, for example, between "application servers" (subscribers) and PSTN gateways (notifiers) operated by the same domain or federation of domains. In this situation a notifier MAY be configured with a list of subscribers which are specifically trusted and authorized to subscribe to key press information related to all sessions in a particular context. The User Interface returns a Contact URI that may have GRUU [9] properties in the Contact header of a SIP INVITE, 1xx, or 2xx response. After authorizing the request, the User Interface checks to see if the request is to terminate a subscription. If the request will terminate the subscription, the User Interface does the appropriate processing, including the procedures described in Section 5.2.
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. The User Interface follows the procedures described in Section 5.2. If the dialog referenced by the kpml subscription does not exist, the User Interface follows the procedures in Section 5.3. Note the User Interface MUST issue a 200 OK to the SUBSCRIBE request before issuing the NOTIFY, as the SUBSCRIBE itself is well formed. If the request has a KPML body, the User Interface parses the KPML document. The User Interface SHOULD validate the XML document against the schema presented in Section 5.2. If the document is not valid, the User Interface rejects the SUBSCRIBE request with an appropriate error response and terminates the subscription. If there is a loaded KPML document on the subscription, the User Interface unloads the document. In addition, if there is a loaded KPML document on the subscription, the end device unloads the document. Following the semantics of SUBSCRIBE, if the User Interface receives a resubscription, the User Interface MUST terminate the existing KPML request and replace it with the new request. It is possible for the INVITE usage of the 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 buffered User Input, then the User Interface attempts to process the buffered digits against the document. If there is a match, the User Interface 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 Interface (notifier), then the User Interface 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 RFC 3265 [5], the User Interface MUST terminate the SIP SUBSCRIBE dialog. The User Interface 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 subscriptions. If a SUBSCRIBE request references a dialog that is not present at the User Interface, the User Interface MUST generate a KPML report with the KPML status code 481, Dialog Not Found. The User Interface terminates the subscription by setting the subscription state to "terminated". If the KPML document is not valid, the User Interface generates a KPML report with the KPML status code 501, Bad Document. The User Interface terminates the subscription by setting the subscription state to "terminated". If the document is valid but the User Interface does not support a namespace in the document, the User Interface MUST respond with a KPML status code 502, Namespace Not Supported.4.8. Notifier Generation of NOTIFY Requests
Immediately after a subscription is accepted, the Notifier MUST send a NOTIFY with the current location information as appropriate based on the identity of the subscriber. This allows the Subscriber to resynchronize its state. The User Interface (notifier in SUBSCRIBE/NOTIFY parlance) generates NOTIFY requests based on the requirements of RFC 3265 [5]. Specifically, if a SUBSCRIBE request is valid and authorized, it will result in an immediate NOTIFY. The KPML payload distinguishes between an initial NOTIFY and a NOTIFY informing of key presses. If there is no User Input buffered at the time of the SUBSCRIBE (see below) or the buffered User Input does not match the new KPML document, then the immediate NOTIFY MUST NOT contain a KPML body. If User Interface has User Input buffered that results in a match using the new KPML document, then the NOTIFY MUST return the appropriate KPML document. The NOTIFY in response to a SUBSCRIBE request has no KPML if there are no matching buffered digits. An example of this is in Figure 10.
If there are buffered 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. NOTIFY sip:application@example.com SIP/2.0 Via: SIP/2.0/UDP proxy.example.com Max-Forwards: 70 To: <sip:application@example.com> From: <sip:endpoint@example.net> Call-Id: 439hu409h4h09903fj0ioij Subscription-State: active; expires=7200 CSeq: 49851 NOTIFY Event: kpml Figure 10: Immediate NOTIFY Example All subscriptions MUST be authenticated, particularly those that match on buffered input. KPML specifies the key press notification report format. The MIME type for KPML reports is application/kpml-response+xml. The default MIME type for the kpml event package is application/ kpml-response+xml. If the requestor is not using a secure transport protocol such as TLS for every hop (e.g., by using a sips: URI), the User Interface SHOULD use S/MIME to protect the user information in responses. When the user enters key presses that match a <regex> tag, the User Interface 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 Interface 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. KPML reports have two mandatory attributes, code and text. These attributes describe the state of the KPML interpreter on the User Interface. Note the KPML status 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 status 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 Interface will most likely set the Subscription-State to
"terminated". This lets the SIP machinery know the subscription is
no longer active.
If a pattern matches, the User Interface will emit a KPML report.
Since this is a success report, the code is "200", and the text is
"OK".
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 and the User
Interface 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 it 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 <response> tag.
Note that if the monitored (INVITE-initiated) dialog terminates, the
notifier still MUST explicitly terminate the KPML subscriptions
monitoring that dialog.
4.9. Subscriber Processing of NOTIFY Requests
If there is no KPML body, it means the SUBSCRIBE was successful.
This establishes the dialog if there is no buffered User Input to
report.
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 between 400
and 499, then an error occurred with User Input collection. The most
likely cause is a timeout condition.
If there is a KPML document, and the KPML status code is between 500 and 599, then an error occurred with the subscription. See Section 6 for more on the meaning of KPML status codes. The subscriber MUST be mindful of the subscription state. The User Interface may terminate the subscription at any time.4.10. Handling of Forked Requests
Forked requests are NOT ALLOWED for this event type. This can be ensured if the Subscriptions to this event package are sent to SIP URIs that have GRUU properties.4.11. Rate of Notifications
The User Interface MUST NOT generate messages faster than 25 messages per second, or 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 <regex> is "x". The sustained rate of notification shall be no more than 100 Notifies per minute. The User Interface MUST reliably deliver notifications. Because there is no meaningful metric for throttling requests, the User Interface SHOULD send NOTIFY messages over a congestion-controlled transport, such as TCP. Note that all SIP implementations are already required to implement SIP over TCP.4.12. State Agents and Lists
KPML requests are sent to a specific SIP URI, which may have GRUU properties, and they attempt to monitor a specific stream that corresponds with a specific target dialog. Consequently, implementers MUST NOT define state agents for this event package or allow subscriptions for this event package to resource lists using the event list extension [18].
4.13. Behavior of a Proxy Server
There are no additional requirements on a SIP Proxy, other than to transparently forward the SUBSCRIBE and NOTIFY methods as required in SIP.5. Formal Syntax
5.1. DRegex
The following definition follows RFC 4234 [2]. The definition of DIGIT is from RFC 4234, namely, the characters "0" through "9". Note the DRegexCharacter is not a HEXDIG from RFC 4234. In particular, DRegexCharacter includes neither "E" nor "F". Note that DRegexCharacter is case insensitive. DRegex = 1*( DRegexPosition [ RepeatCount ] ) DRegexPosition = DRegexSymbol / DRegexSet DRegexSymbol = [ "L" ] DRegexCharacter DRegexSet = "[" 1*DRegexSetList "]" DRegexSetList = DRegexCharacter [ "-" DRegexCharacter ] DRegexCharacter = DIGIT / "A" / "B" / "C" / "D" / "R" / "*" / "#" / "a" / "b" / "c" / "d" / "r" RepeatCount = "." / "{" RepeatRange "}" RepeatRange = Count / ( Count "," Count ) / ( Count "," ) / ( "," Count ) Count = 1*DIGIT ABNF for DRegex Note that future extensions to this document may introduce other characters for DRegexCharacter, in the scheme of H.248.1 [12] or possibly as named strings or XML namespaces.
5.2. KPML Request
The following syntax for KPML requests uses the XML Schema [8]. <?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="urn:ietf:params:xml:ns:kpml-request" xmlns="urn:ietf:params:xml:ns:kpml-request" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="kpml-request"> <xs:annotation> <xs:documentation>IETF Keypad Markup Language Request </xs:documentation> </xs:annotation> <xs:complexType> <xs:sequence> <xs:element name="stream" minOccurs="0"> <xs:complexType> <xs:choice> <xs:element name="reverse" minOccurs="0"/> <xs:any namespace="##other"/> </xs:choice> </xs:complexType> </xs:element> <xs:element name="pattern"> <xs:complexType> <xs:sequence> <xs:element name="flush" minOccurs="0"> <xs:annotation> <xs:documentation> Default is to not flush buffer </xs:documentation> </xs:annotation> <xs:complexType> <xs:simpleContent> <xs:extension base="xs:string"/> </xs:simpleContent> </xs:complexType> </xs:element> <xs:element name="regex" maxOccurs="unbounded"> <xs:annotation> <xs:documentation> Key press notation is a string to allow for future extension of non-16 digit keypads or named keys </xs:documentation> </xs:annotation>
<xs:complexType mixed="true">
<xs:choice>
<xs:element name="pre" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string"/>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:any namespace="##other"/>
</xs:choice>
<xs:attribute name="tag" type="xs:string"
use="optional"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="persist" use="optional">
<xs:annotation>
<xs:documentation>Default is "one-shot"
</xs:documentation>
</xs:annotation>
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="one-shot"/>
<xs:enumeration value="persist"/>
<xs:enumeration value="single-notify"/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="interdigittimer"
type="xs:integer"
use="optional">
<xs:annotation>
<xs:documentation>Default is 4000 (ms)
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="criticaldigittimer"
type="xs:integer"
use="optional">
<xs:annotation>
<xs:documentation>Default is 1000 (ms)
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="extradigittimer"
type="xs:integer"
use="optional">
<xs:annotation> <xs:documentation>Default is 500 (ms) </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="long" type="xs:integer" use="optional"/> <xs:attribute name="longrepeat" type="xs:boolean" use="optional"/> <xs:attribute name="nopartial" type="xs:boolean" use="optional"> <xs:annotation> <xs:documentation>Default is false </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="enterkey" type="xs:string" use="optional"> <xs:annotation> <xs:documentation>No default enterkey </xs:documentation> </xs:annotation> </xs:attribute> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="version" type="xs:string" use="required"/> </xs:complexType> </xs:element> </xs:schema> Figure 12: XML Schema for KPML Requests
5.3. KPML Response
The following syntax for KPML responses uses the XML Schema [8]. <?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="urn:ietf:params:xml:ns:kpml-response" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:ietf:params:xml:ns:kpml-response" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="kpml-response"> <xs:annotation> <xs:documentation>IETF Keypad Markup Language Response </xs:documentation> </xs:annotation> <xs:complexType> <xs:attribute name="version" type="xs:string" use="required"/> <xs:attribute name="code" type="xs:string" use="required"/> <xs:attribute name="text" type="xs:string" use="required"/> <xs:attribute name="suppressed" type="xs:boolean" use="optional"/> <xs:attribute name="forced_flush" type="xs:string" use="optional"> <xs:annotation> <xs:documentation> String for future use for e.g., number of digits lost. </xs:documentation> </xs:annotation> </xs:attribute> <xs:attribute name="digits" type="xs:string" use="optional"/> <xs:attribute name="tag" type="xs:string" use="optional"> <xs:annotation> <xs:documentation>Matches tag from regex in request </xs:documentation> </xs:annotation> </xs:attribute> </xs:complexType> </xs:element> </xs:schema> XML Schema for KPML Responses
6. Enumeration of KPML Status Codes
KPML status 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. +------+--------------------------------------------------+ | Code | Text | +------+--------------------------------------------------+ | 200 | Success | | 402 | User Terminated without Match | | 423 | Timer Expired | | 481 | Dialog Not Found | | 487 | Subscription Expired | | 501 | Bad Document | | 502 | Namespace Not Supported | | 531 | Persistent Subscriptions Not Supported | | 532 | Multiple Regular Expressions Not Supported | | 533 | Multiple Subscriptions on a Dialog Not Supported | | 534 | Too Many Regular Expressions | +------+--------------------------------------------------+ Table 4: KPML Status Codes7. IANA Considerations
This document registers a new SIP Event Package, two new MIME types, and two new XML namespaces.7.1. SIP Event Package Registration
Package name: kpml Type: package Contact: Eric Burger, <e.burger@ieee.org> Change Controller: SIPPING Working Group delegated from the IESG Published Specification: RFC 4730
7.2. MIME Media Type application/kpml-request+xml
MIME media type name: application MIME subtype name: kpml-request+xml Required parameters: none Optional parameters: Same as charset parameter application/xml as specified in XML Media Types [3] Encoding considerations: See RFC 3023 [3]. Security considerations: See Section 10 of RFC 3023 [3] and Section 8 of RFC 4730 Interoperability considerations: See RFC 2023 [3] and RFC 4730 Published specification: RFC 4730 Applications which use this media type: Session-oriented applications that have primitive User Interfaces. Change controller: SIPPING Working Group delegated from the IESG Personal and email address for further information: Eric Burger <e.burger@ieee.org> Intended usage: COMMON7.3. MIME Media Type application/kpml-response+xml
MIME media type name: application MIME subtype name: kpml-response+xml Required parameters: none Optional parameters: Same as charset parameter application/xml as specified in XML Media Types [3] Encoding considerations: See RFC 3023 [3]. Security considerations: See Section 10 of RFC 3023 [3] and Section 8 of RFC 4730 Interoperability considerations: See RFC 2023 [3] and RFC 4730 Published specification: RFC 4730 Applications which use this media type: Session-oriented applications that have primitive User Interfaces. Change controller: SIPPING Working Group delegated from the IESG Personal and email address for further information: Eric Burger <e.burger@ieee.org> Intended usage: COMMON7.4. URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-request
URI: urn:ietf:params:xml:ns:kpml-request Registrant Contact: The IESG <iesg@ietf.org>
XML:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C/DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Key Press Markup Language Request</title>
</head>
<body>
<h1>Namespace for Key Press Markup Language Request</h1>
<h2>urn:ietf:params:xml:ns:kpml-request</h2>
<p>
<a href="ftp://ftp.rfc-editor.org/in-notes/RFC4730.txt">RFC 4730</a>.
</p>
</body>
</html>
7.5. URN Sub-Namespace Registration for urn:ietf:xml:ns:kpml-response
URI: urn:ietf:params:xml:ns:kpml-response
Registrant Contact: The IESG <iesg@ietf.org>
XML:
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C/DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Key Press Markup Language Response</title>
</head>
<body>
<h1>Namespace for Key Press Markup Language Response</h1>
<h2>urn:ietf:params:xml:ns:kpml-response</h2>
<p>
<a href="ftp://ftp.rfc-editor.org/in-notes/rfc4730.txt">RFC 4730</a>.
</p>
</body>
</html>
7.6. KPML Request Schema Registration
Per RFC 3688 [7], IANA registered the XML Schema for KPML as referenced in Section 5.2 of RFC 4730. URI: urn:ietf:params:xml:schema:kpml-request Registrant Contact: <iesg@ietf.org>7.7. KPML Response Schema Registration
Per RFC 3688 [7], IANA registered the XML Schema for KPML as referenced in Section 5.3 of RFC 4730. URI: urn:ietf:params:xml:schema:kpml-response Registrant Contact: IETF, SIPPING Work Group <sipping@ietf.org>, Eric Burger <e.burger@ieee.org>.
(page 37 continued on part 3)
