A Session Initiation Protocol (SIP) Event Package for Key Press Stimulus (KPML)
Extracted elements (30)
DRegex (Digit Regular Expression) uses a telephony-oriented subset of POSIX ERE rather than full POSIX ERE, for three reasons: (1) KPML targets small memory/processing footprint devices; (2) telephony convention uses '*' for the star key and 'x' for any digit 0-9, which conflicts with POSIX use of '*' for repetition; (3) the alternation operator '|' caused implementer confusion in MGCP and H.248, so DRegex replaces it with multiple <regex> elements.
KPML does not use the POSIX alternation operator '|' because implementation experience with MGCP and H.248.1 showed that users and implementers have persistent difficulty understanding alternation precedence. Instead, each <pattern> element may contain multiple <regex> elements, providing pattern alternatives without the ambiguity of inline alternation.
KPML uses greedy (longest) matching aligned with H.248.1, not shortest-match as in MGCP. This allows distinguishing overlapping patterns such as '0', '00', '011', and '0011'. The critical-digit timer enables waiting for a longer match after the shortest match is already found.
The default subscription duration is 7200 seconds; subscriptions in hours or days are RECOMMENDED. Subscribers MUST be able to handle the User Interface returning an Expires value smaller than the requested value, per RFC 3265 — the actual subscription duration is the value in the 200 OK Expires header returned by the notifier.
Forked SUBSCRIBE requests are NOT ALLOWED for the kpml event package. KPML subscriptions MUST NOT fork; sending SUBSCRIBEs to SIP URIs with GRUU properties ensures this.
If a User Interface detects a key press that triggers a one-shot KPML event, it MUST set the 'Subscription-State' header in the NOTIFY to 'terminated' and MUST consider the subscription expired.
If the User Interface discards buffered digits due to buffer overflow, it MUST set the 'forced_flush' attribute of the <response> element to 'true' in the NOTIFY. Subscribers MUST treat any non-null, non-'false' value of 'forced_flush' that they do not recognize as equivalent to 'true'.
If the User Interface supports the inter-digit timer specification but not at the requested granularity, it MUST round up the requested value to the closest supported value. If it does not support specification at all, it MUST silently ignore the specification.
If there is a <pre> tag that the User Interface matched but the User Interface is unable to suppress the User Input, it MUST set the 'suppressed' attribute to 'false'. Once a NOTIFY reporting the match is sent, the User Interface MUST stop suppression.
Implementers MUST NOT define state agents for the kpml event package and MUST NOT allow subscriptions to resource lists using the event list extension, because KPML subscriptions target a specific SIP URI and dialog.
KPML clients MUST be able to handle arbitrary KPML status codes by examining the first digit only, and MUST NOT interpret the text field of a KPML report.
KPML User Interfaces MUST follow the deterministic pattern-match algorithm: the longest matching regular expression wins. If multiple expressions match at the same length, the User Interface MUST choose the first expression listed in the KPML document (document order).
The KPML request document MUST be well-formed and SHOULD be valid XML. KPML documents MUST conform to XML 1.0 and MUST use UTF-8 encoding.
The three Event Package parameters call-id, remote-tag, and local-tag MUST be present in the SUBSCRIBE Event header to identify the subscription dialog. The User Interface matches local-tag against the To tag, remote-tag against the From tag, and call-id against the Call-ID.
The User Interface MUST NOT generate NOTIFY messages faster than 25 messages per second (one message per 40 milliseconds). The sustained rate MUST be no more than 100 NOTIFYs per minute. KPML strongly RECOMMENDS AGAINST digit-by-digit messaging (e.g., using only '<regex>x</regex>').
The User Interface (notifier) MUST authenticate the requesting party before accepting a KPML subscription. User Interfaces MUST implement SIP Digest authentication, the sips: scheme, and TLS. Subscribers MUST be prepared for the notifier to demand authentication and a secure channel.
User Interfaces MUST buffer User Input upon receipt of an authenticated and accepted subscription. They MUST NOT provide a subscriber with digits detected prior to the authentication and authorization of that subscriber, to prevent access to pre-existing calling card or credit card input.
Digit suppression is controlled by a <pre> element inside a <regex> tag; at most one <pre> tag is allowed per <regex>. Once the User Interface accumulates input matching the <pre> prefix, it suppresses further in-band DTMF/RFC 2833 forwarding and continues collecting digits. The 'suppressed' attribute in the response indicates whether suppression occurred.
KPML defines three subscription types via the 'persist' attribute on the <pattern> element: 'one-shot' (terminates after first match), 'persist' (continuous-notify, remains active and fires on every match), and 'single-notify' (fires once then waits for a new subscription request before firing again, enabling lock-step digit collection).
KPML status codes follow SIP conventions: 2xx indicates success (200 = OK); 4xx indicates User Input collection failures (402 = User Terminated without Match, 423 = Timer Expired, 481 = Dialog Not Found, 487 = Subscription Expired); 5xx indicates server/document failures (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).
Long key presses are signaled using the 'L' modifier preceding a character in a <regex> (e.g., 'L#' for a long pound). The 'long' attribute on <pattern> specifies the minimum duration in milliseconds (default 2500 ms). The 'longrepeat' boolean attribute allows repeated short presses of the same key to substitute for a long press.
The 'enterkey' attribute on the <pattern> element specifies a key sequence (e.g., '#') that immediately terminates pattern matching. If the user presses the enterkey after a partial match, KPML reports status code 402 (User Terminated without Match). The enterkey is a string and may be a multi-key sequence such as '**'.
The 'kpml' SIP Event Package enables monitoring of DTMF key presses using SUBSCRIBE/NOTIFY methods. Applications send application/kpml-request+xml bodies in SUBSCRIBE to specify digit patterns; the User Interface sends application/kpml-response+xml bodies in NOTIFY when digits are collected, timed out, or an error occurs.
Three timers govern digit collection: the inter-digit timer (default 4000 ms) is the maximum wait between digits; the critical-digit timer (default 1000 ms) is the wait when a match exists but a longer match is still possible; the extra-digit timer (default 500 ms) is the wait when the longest match has been reached but an enterkey may follow.
This document registers the SIP Event Package named 'kpml' (package type), two MIME media types (application/kpml-request+xml and application/kpml-response+xml), two URN sub-namespaces (urn:ietf:params:xml:ns:kpml-request and urn:ietf:params:xml:ns:kpml-response), and two XML schema registrations (urn:ietf:params:xml:schema:kpml-request and urn:ietf:params:xml:schema:kpml-response).
KPML-transported data is potentially sensitive (calling card numbers, credit card numbers, PINs). The notifier must authenticate and authorize all subscribers; improper authorization could leak buffered digits from earlier in the session to a new subscriber. Eavesdroppers can view digit information if not encrypted; attackers can inject fraudulent NOTIFYs without integrity protection.
User Interfaces MUST NOT downgrade their own security policy: if policy restricts notifications to authenticated subscribers over secure channels, the User Interface must reject unauthenticated or insecure subscriptions. Signaling SHOULD use TLS and sips:; content SHOULD be protected with S/MIME or equivalent mechanisms.
The DRegex ABNF defines: DRegex = 1*(DRegexPosition [RepeatCount]); DRegexPosition is a DRegexSymbol or DRegexSet; DRegexSymbol is an optional 'L' (long) modifier followed by a DRegexCharacter (digits 0-9, A-D, R, *, #, case-insensitive); RepeatCount is '.' (zero or more) or a curly-brace range quantifier.
The kpml-request XML schema defines a <kpml-request> root element containing an optional <stream> element and a mandatory <pattern> element. The <pattern> holds an optional <flush> element and one or more <regex> elements, and carries attributes: persist, interdigittimer, criticaldigittimer, extradigittimer, long, longrepeat, nopartial, and enterkey. The root element requires a 'version' attribute.
The kpml-response XML schema defines a <kpml-response> element with required attributes 'version', 'code' (KPML status code string), and 'text', and optional attributes 'suppressed' (boolean), 'forced_flush' (string), 'digits' (matched digit string), and 'tag' (echoes the matching <regex> tag attribute).