A Baisc Profile of the Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML)
draft-burger-sipping-kpml-basic-00

Status of this Memo

By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79.

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 May 15, 2008.

Abstract

This document describes a profile of the SIP Event Package "kpml" that enables simple monitoring of DTMF signals and uses XML documents referred to as Key Press Markup Language (KPML). This profile assumes devices of lesser capability that may have trouble parsing subscription requests or producing generic XML documents. This is a profile of RFC 4730, KPML.

Conventions used in this document

RFC2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119] 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 document (Rosenberg, J., “A Framework for Application Interaction in the Session Initiation Protocol (SIP),” July 2005.) [I‑D.ietf‑sipping‑app‑interaction‑framework] 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".

Additionally, the Application Interaction Framework document 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.

Table of Contents

1.  Introduction
2.  Protocol Overview
3.  Event Package Formal Definition
    3.1.  Event Package Name
    3.2.  Event Package Parameters
    3.3.  SUBSCRIBE Bodies
    3.4.  Subscription Duration
    3.5.  NOTIFY Bodies
    3.6.  Subscriber generation of SUBSCRIBE requests
    3.7.  Notifier processing of SUBSCRIBE requests
    3.8.  Notifier generation of NOTIFY requests
    3.9.  Subscriber processing of NOTIFY requests
    3.10.  Handling of Forked Requests
    3.11.  Rate of notifications
    3.12.  State Agents and Lists
    3.13.  Behavior of a Proxy Server
4.  IANA Considerations
    4.1.  SIP Event Package Registration
5.  Security Considerations
6.  References
    6.1.  Normative References
    6.2.  Informative References
Appendix A.  Contributors
Appendix B.  Acknowledgements
§  Author's Address
§  Intellectual Property and Copyright Statements

1.  Introduction

This document describes a profile for the SIP Event Package "kpml" that enables monitoring of key presses and utilizes XML documents referred to as Key Press Markup Language (KPML) (Burger, E. and M. Dolly, “A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML),” November 2006.) [RFC4730], RFC 4730.

A goal of KPML is to fit in an extremely small memory and processing footprint. However, some believe that even with this lightweight goal, the burden of parsing generic XML subscription requests and generating arbitrary XML is too complex. This document provides a basic profile that eliminates the requirement of a KPML server to parse arbitrary subscription requests or generate arbitrary XML documents.

Of course, we strongly suggest implementing the full KPML protocol. However, this profile provides the benefits of KPML, namely not sharing the SIP dialog with the underlying SIP session. Note that by reporting on a digit-by-digit basis, quite a lot of bandwidth and packets are wasted. That said, with the exception of subscription establishment, this mechanism uses virtually identical bandwidth, and identical packet use, of INFO-based digit reporting schemes.

We considered having the invite, offering a kpml-basic event, to automatically generate a subscription for the kpml-basic profile. However, this is not workable, because the client making the request has no way of correlating the automatically generated subscription to the underlying SIP session. This is differnt from the REFER (Sparks, R., “The Session Initiation Protocol (SIP) Refer Method,” April 2003.) [RFC3515] situation, where the new REFER dialog establishes the subscription dialog.

2.  Protocol Overview

As a profile of KPML, the protocol operates identically to KPML. However, by advertising the kpml-basic event package, as opposed to kpml, the protocol described in this document superceeds the negotiation of KPML. In particular, the server MUST ignore any subscription body and substitute it with an expression similar to Figure 1 (Sample Default Request). This matches every key press and reports on every key press.

The server can optimize reporting by using a template XML document, substituting only the particular key press entered into the template.

The client assumes a persistent subscription.

3.  Event Package Formal Definition

3.1.  Event Package Name

This document defines a SIP Event Package as defined in RFC 3265 (Roach, A., “Session Initiation Protocol (SIP)-Specific Event Notification,” June 2002.) [RFC3265]. The event-package token name for this package is:

"kpml-basic"

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

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.

3.3.  SUBSCRIBE Bodies

Applications using this event package have an empty body in the SUBSCRIBE request. The server MUST interpret this request as if it had a document requesting every possible single key press pattern. A sample of an application/kpml-request+xml document follows. Note if there are other defined digits, the server includes them in the pattern

<?xml version="1.0">
<kpml-request xmlns="urn:ietf:params:xml:ns:kpml-request"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation=
        "urn:ietf:params:xml:ns:kpml-request kpml-request.xsd"
      version="1.0">
  <pattern>
    <regex>[0123456789ABCDR*#]</regex>
  </pattern>
</kpml-request>

3.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 RFC3265 (Roach, A., “Session Initiation Protocol (SIP)-Specific Event Notification,” June 2002.) [RFC3265], the subscription duration is the value returned by the Notifier in the 200 OK Expires header.

3.5.  NOTIFY Bodies

NOTIFY requests MUST contain well-formed application/kpml-response+xml (KPML Response) bodies. The syntax of this body type is formally described in RFC 4730.

The KPML server MAY use a template such as the following to send its responses.

?xml version="1.0" encoding="UTF-8"?>
<kpml-response xmlns="urn:ietf:params:xml:ns:kpml-response"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation=
        "urn:ietf:params:xml:ns:kpml-response kpml-response.xsd"
      version="1.0"
      code="200" text="OK"
      digits="2"/>

In the above example, the key pressed was a "2". Presumably, the KPML server would fill in the exact key pressed instead of the 2.

It is very important to note the KPML client (the subscriber) MUST be capable of parsing arbitrary XML documents. There is no guarantee the server will use the above template. Since the server can use any legal, well-formed, application/kpml-response+xml template. There is no guarantee the server will use the above example as its template.

Notifiers MAY send notifications with any format acceptable to the subscriber (based on the subscriber 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.

3.6.  Subscriber generation of SUBSCRIBE requests

A kpml-basic request has no attached document.

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.

3.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 RFC3261 (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) [RFC3261] 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. Determining authorization policies and procedures is beyond the scope of this specification.

The User Interface returns a Contact URI that may have GRUU (Rosenberg, J., “Obtaining and Using Globally Routable User Agent (UA) URIs (GRUU) in the Session Initiation Protocol (SIP),” October 2007.) [I‑D.ietf‑sip‑gruu] properties in the Contact header of a SIP INVITE, 1xx, or 2xx response.

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) and there is buffered User Input, 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 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. This could be the null string.

Per the mechanisms of RFC3265 (Roach, A., “Session Initiation Protocol (SIP)-Specific Event Notification,” June 2002.) [RFC3265], 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".

3.8.  Notifier generation of NOTIFY requests

The User Interface (notifier in SUBSCRIBE/NOTIFY parlance) generates NOTIFY requests based on the requirements of RFC3265 (Roach, A., “Session Initiation Protocol (SIP)-Specific Event Notification,” June 2002.) [RFC3265]. 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 result 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.

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.

Note that if the monitored (INVITE-initiated) dialog terminates, the Notifier still MUST explicitly terminate the KPML subscriptions monitoring that dialog.

3.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 RFC 4730 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.

3.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 which have GRUU properties.

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

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.

3.12.  State Agents and Lists

KPML requests are sent to a specific SIP URI, which may have GRUU properties, and attempt to monitor a specific stream that corresponds with a specific target dialog. Consequently, implementers MUST NOT define state agents for this event package nor allow subscriptions for this event package to resource lists using the event list extension (Roach, A., Campbell, B., and J. Rosenberg, “A Session Initiation Protocol (SIP) Event Notification Extension for Resource Lists,” August 2006.) [RFC4662].

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

4.  IANA Considerations

This document registers a new SIP Event Package.

4.1.  SIP Event Package Registration

Package name:

kpml-basic

Type:

package

Contact:

Eric Burger, <eburger@standardstrack.com>

Change Controller:

SIPPING Working Group delegated from the IESG

Published Specification:

RFCXXXX

5.  Security Considerations

The user information transported by KPML is potentially sensitive. For example, it could include calling card or credit card numbers. This potentially private information could be provided accidentally if the notifier does not properly authenticate or authorize a subscription. Similarly private information (such as a credit card number or calling card number) could be revealed to an otherwise legitimate subscriber (one operating an IVR) if digits buffered earlier in the session are provided unintentionally to the new subscriber.

Likewise, an eavesdropper could view KPML digit information if it is not encrypted, or an attacker could inject fraudulent notifications unless the messages or the SIP path over which they travel are integrity protected.

Therefore, User Interfaces MUST NOT downgrade their own security policy. That is, if a User Interface policy is to restrict notifications to authenticated and authorized subscribers over secure communications, then the User Interface must not accept an unauthenticated, unauthorized subscription over an insecure communication channel.

As an XML markup, all of the security considerations of RFC3023 (Murata, M., St. Laurent, S., and D. Kohn, “XML Media Types,” January 2001.) [RFC3023] and RFC3406 (Daigle, L., van Gulik, D., Iannella, R., and P. Faltstrom, “Uniform Resource Names (URN) Namespace Definition Mechanisms,” October 2002.) [RFC3406] must be met. Pay particular attention to the robustness requirements of parsing XML.

Key press information is potentially sensitive. For example, it can represent credit card, calling card, or other personal information. 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; therefore the use of S/MIME or other appropriate mechanism SHOULD be used.

Subscriptions MUST be authenticated in some manner. As required by the core SIP (Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, “SIP: Session Initiation Protocol,” June 2002.) [RFC3261] specification, all SIP implementations MUST support digest authentication. In addition, User Interfaces MUST implement support for the sips: scheme and SIP over TLS. Subscribers MUST expect the User Interface to demand the use of an authentication scheme. If the local policy of a User Interface is to use authentication or secure communication channels, the User Interface MUST reject subscription requests that do not meet that policy.

User Interfaces MUST begin buffering User Input upon receipt of an authenticated and accepted subscription. This buffering is done on a per subscription basis.

6.  References

6.1. Normative References

6.2. Informative References

Appendix A.  Contributors

This is my own invention, but we cannot forget the many people who contributed to KPML, RFC 4730.

Appendix B.  Acknowledgements

Rohan Mahy asked for this one time too many.

Author's Address

Full Copyright Statement

Copyright © The IETF Trust (2007).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an “AS IS” basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.