Internet Engineering Task Force IPTEL WG Internet Draft Lennox/Schulzrinne draft-ietf-iptel-cpl-01.txt Columbia University March 10, 2000 Expires: September 2000 CPL: A Language for User Control of Internet Telephony Services 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. Abstract The Call Processing Language (CPL) is a language that can be used to describe and control Internet telephony services. It is designed to be implementable on either network servers or user agent servers. It is meant to be simple, extensible, easily edited by graphical clients, and independent of operating system or signalling protocol. It is suitable for running on a server where users may not be allowed to execute arbitrary programs, as it has no variables, loops, or ability to run external programs. This document is a product of the IP Telephony (IPTEL) working group of the Internet Engineering Task Force. Comments are solicited and should be addressed to the working group's mailing list at iptel@lists.research.bell-labs.com and/or the authors. 1 Introduction The Call Processing Language (CPL) is a language that can be used to Lennox/Schulzrinne [Page 1] Internet Draft CPL March 10, 2000 describe and control Internet telephony services. It is not tied to any particular signalling architecture or protocol; it is anticipated that it will be used with both SIP [1] and H.323 [2]. The CPL is powerful enough to describe a large number of services and features, but it is limited in power so that it can run safely in Internet telephony servers. The intention is to make it impossible for users to do anything more complex (and dangerous) than describing Internet telephony services. The language is not Turing-complete, and provides no way to write loops or recursion. The CPL is also designed to be easily created and edited by graphical tools. It is based on XML [3], so parsing it is easy and many parsers for it are publicly available. The structure of the language maps closely to its behavior, so an editor can understand any valid script, even ones written by hand. The language is also designed so that a server can easily confirm scripts' validity at the time they are delivered to it, rather that discovering them while a call is being processed. Implementations of the CPL are expected to take place both in Internet telephony servers and in advanced clients; both can usefully process and direct users' calls. In the former case, a mechanism will be needed to transport scripts between clients and servers; this document does not describe such a mechanism, but related documents will. The framework and requirements for the CPL architecture are described in the document "Call Processing Language Framework and Requirements," which will be an Informational RFC; it is currently available as the Internet-Draft draft-ietf-iptel-cpl-framework-02 [4]. 1.1 Conventions of this document In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [5] and indicate requirement levels for compliant CPL implementations. In examples, non-XML strings such as -action1, -action2, and so forth, are sometimes used. These represent further parts of the script which are not relevant to the example in question. Some paragraphs are indented, like this; they give motivations of design choices, or questions for future discussion in the development of the CPL, and are not Lennox/Schulzrinne [Page 2] Internet Draft CPL March 10, 2000 essential to the specification of the language. 2 Structure of CPL scripts 2.1 High-level structure A CPL script consists of two types of information: ancillary information about the script, and call processing actions. A call processing action is a structured tree that describes the decisions and actions a telephony signalling server performs on a call set-up event. There are two types of call processing actions: top-level actions are actions that are triggered by signalling events that arrive at the server. Two top-level action names are defined: incoming, the action performed when a call arrives whose destination is the owner of the script; and outgoing, the action performed when a call arrives whose originator is the owner of the script. Sub-actions are actions which can be called from other actions. The CPL forbids sub-actions from being called recursively: see section 8. Note: The names "action," "sub-action," and "top-level action" are probably not ideal. Suggestions for better names for these concepts are welcomed. Ancillary information is information which is necessary for a server to correctly process a script, but which does not directly describe any actions. Currently, the only type of ancillary information defined is timezone definitions; see section 9. 2.2 Abstract structure of a call processing action Abstractly, a call processing action is described by a collection of nodes, which describe actions that can be performed or choices which can be made. A node may have several parameters, which specify the precise behavior of the node; they usually also have outputs, which depend on the result of the condition or action. For a graphical representation of a CPL action, see figure 1. Nodes and outputs can be thought of informally as boxes and arrows; the CPL is designed so that actions can be conveniently edited graphically using this representation. Nodes are arranged in a tree, starting at a single root node; outputs of nodes are connected to additional nodes. When an action is run, the action or condition described by the top-level node is performed; based on the result of that node, the server follows one of the node's outputs, and that action or condition is performed; this process continues until a node with no specified outputs is reached. Because the graph is acyclic, this Lennox/Schulzrinne [Page 3] Internet Draft CPL March 10, 2000 will occur after a bounded and predictable number of nodes are visited. If an output to a node is not specified, it indicates that the CPL server should perform a node- or protocol-specific action. Some nodes have specific default actions associated with them; for others, the default action is implicit in the underlying signalling protocol, or can be configured by the administrator of the server. For further details on this, see section 10. _________________ ___________________ ________ busy | Address-switch | | location | | proxy |--------\ Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout| | subfield: host | / | example.com | | 10s |--------| |-----------------|/ |___________________| | | failure| | subaddress-of: | |________|--------| | example.com | | |-----------------| _____________________________________________/ | otherwise | /.......................................... | |\|. Voicemail . |_________________| \. ____________________ . ->| location | __________ . . | url: sip:jones@ | | redirect | . . | voicemail. |--->| | . . | example.com | |__________| . . |____________________| . .......................................... Figure 1: Sample CPL Action: Graphical Version 2.3 Location model For flexibility, one piece of information necessary for the function of a CPL is not given as node parameters: the set of locations to which a call is to be directed. Instead, this set of locations is stored as an implicit global variable throughout the execution of a processing action (and its sub-actions). This allows locations to be retrieved from external sources, filtered, and so forth, without requiring general language support for such actions (which could harm the simplicity and tractability of understanding the language). The Lennox/Schulzrinne [Page 4] Internet Draft CPL March 10, 2000 specific actions which add, retrieve, or filter location sets are given in section 5. For the incoming top-level processing action, the location set is initialized to the empty set. For the outgoing action, it is initialized to the destination address of the call. 2.4 XML structure Syntactically, CPL scripts are represented by XML documents. XML is thoroughly specified by [3], and implementors of this specification should be familiar with that document, but as a brief overview, XML consists of a hierarchical structure of tags; each tag can have a number of attributes. It is visually and structurally very similar to HTML [6], as both languages are simplifications of the earlier and larger standard SGML [7]. See figure 2 for the XML document corresponding to the graphical representation of the CPL script in figure 1. Both nodes and outputs in the CPL are represented by XML tags; parameters are represented by XML tag attributes. Typically, node tags contain output tags, and vice-versa (with one exception; see section 2.3). The connection between the output of a node and another node is represented by enclosing the tag representing the pointed-to node inside the tag for the outer node's output. Convergence (several outputs pointing to a single node) is represented by sub-actions, discussed further in section 8. The higher-level structure of a CPL script is represented by tags corresponding to each piece of meta-information, sub-actions, and top-level actions, in order. This higher-level information is all enclosed in a special tag cpl, the outermost tag of the XML document. A complete Document Type Declaration for the CPL is provided in Appendix A. The remainder of the main sections of this document describe the semantics of the CPL, while giving its syntax informally. For the formal syntax, please see the appendix. 3 Script structure: overview As mentioned, a CPL script consists of ancillary information, subactions, and top-level actions. The full syntax of the cpl node is given in figure 3. Call processing actions, both top-level actions and sub-actions, Lennox/Schulzrinne [Page 5] Internet Draft CPL March 10, 2000
Figure 2: Sample CPL Script: XML Version consist of nodes and outputs. Nodes and outputs are both described by XML tags. There are four categories of CPL nodes: switches , location modifiers , signalling actions , and non-signalling actions. 4 Switches Switches represent choices a CPL script can make, based on either attributes of the original call request or items independent of the call. All switches are arranged as a list of conditions that can match a variable. Each condition corresponds to a node output; the output points to the next node to execute if the condition was true. The conditions are tried in the order they are presented in the script; the output corresponding to the first node to match is taken. Lennox/Schulzrinne [Page 6] Internet Draft CPL March 10, 2000 Node: cpl Parameters: none Outputs: timezone See section 9 subaction See section 8 outgoing Top-level actions to take on this user's outgoing calls incoming Top-level actions to take on this user's incoming calls Output: outgoing Parameters: none Output: incoming Parameters: none Figure 3: Syntax of the top-level cpl tag There are two special switch outputs that apply to every switch type. The output not-present is true if the variable the switch was to match was not present in the original call. The output otherwise, which MUST be the last output specified, matches if no other condition matched. If no condition matches and no otherwise output was present in the script, the default script action is taken. See section 10 for more information on this. 4.1 Address switches Address switches allow a CPL script to make decisions based on one of the addresses present in the original call request. They are summarized in figure 4. Address switches have two node parameters: field, and subfield. The mandatory field parameter allows the script to specify which address is to be considered for the switch: either the call's origin address (field "origin"), its current destination address (field "destination"), or its original destination (field "original- destination"), the destination the call had before any earlier forwarding was invoked. Servers MAY define additional subfield values. The optional subfield specifies what part of the address is to be considered. The possible subfield values are: address-type, user, host, port, tel, and display. Additional subfield values MAY be defined: two additional ones, password and asn1 are defined Lennox/Schulzrinne [Page 7] Internet Draft CPL March 10, 2000 Node: address-switch Outputs: address Specific addresses to match Parameters: field origin, destination, or original-destination subfield address-type, user, host, port, tel, display, password, or asn1 Output: address Parameters: is exact match contains substring match (for display only) subdomain-of sub-domain match (for host, tel only) Figure 4: Syntax of the address-switch node specifically for SIP and H.323 respectively, in sections 4.1.1 and 4.1.2 below. If no subfield is specified, the "entire" address is matched; the precise meaning of this is defined for each underlying signalling protocol. The subfields are defined as follows: address-type This indicates the type of the underlying address; i.e., the URI scheme, if the address can be represented by the URI. The types specifically discussed by this document are sip, tel, and h323. The address type is not case- sensitive; it is always present if the address is present. user This subfield of the address indicates, for e-mail style addresses, the user part of the address. For telephone number style address, it includes the subscriber number. This subfield is case-sensitive; it may be not present. host This subfield of the address indicates the Internet host name or IP address corresponding to the address, in host name, IPv4, or IPv6 format. For host names only, subdomain matching is supported with the subdomain-of match operator. It is not case sensitive, and may be not present. port This subfield indicates the TCP or UDP port number of the address, numerically in decimal format. It is not case sensitive, as it MUST only contain decimal digits. It may be not present; however, for address types with default ports, an absent port matches the default port number. tel This subfield indicates a telephone subscriber number, if the address contains such a number. It is not case Lennox/Schulzrinne [Page 8] Internet Draft CPL March 10, 2000 sensitive (the telephone numbers may contain the symbols `A' `B' `C' and `D'), and may be not present. It may be matched using the subdomain-of match operator. Punctuation and separator characters in telephone numbers are discarded. display This subfield indicates a "display name" or user-visible name corresponding to an address. It is a Unicode string, and is matched using the case-insensitive algorithm described in section 4.2. The contains operator may be applied to it. It may be not present. For any completely unknown subfield, the server MAY reject the script at the time it is submitted with an indication of the problem; if a script with an unknown subfield is executed, the server MUST consider the not-present output to be the valid one. The address output tag may take exactly one of three possible parameters, indicating the kind of matching allowed. is An output with this match operator is followed if the subfield being matched in the address-switch exactly matches the argument of the operator. It may be used for any subfield, or for the entire address if no subfield was specified. subdomain-of This match operator applies only for the subfields host and tel. In the former case, it matches if the hostname being matched is a subdomain of the domain given in the argument of the match operator; thus, match="example.com" would match the hostnames "example.com", "research.example.com", and "zaphod.sales.internal.example.com". IP addresses may be given as arguments to this operator; however, they only match exactly. In the case of the tel subfield, the output matches if the telephone number being matched has a prefix that matches the argument of the match operator; match="1212555" would match the telephone number "1 212 555 1212." contains This match operator applies only for the subfield display. The output matches if the display name being matched contains the argument of the match as a substring. 4.1.1 Address switch mapping for SIP For SIP, the origin address corresponds to the address in the From header; destination corresponds to the Request-URI; and original- Lennox/Schulzrinne [Page 9] Internet Draft CPL March 10, 2000 destination corresponds to the To header. The display subfield of an address is the display-name part of the address, if it is present. Because of SIP's syntax, the destination address field will never have a display subfield. The address-type subfield of an address is the URI scheme of that address. Other address fields depend on that address-type. For sip URLs, the user, host, and port subfields correspond to the "user," "host," and "port" elements of the URI syntax. The tel subfield is defined to be the "user" part of the URI if and only if the "user=phone" parameter is given to the URI. An additional subfield, password is defined to correspond to the "password" element of the SIP URI; however, use of this field is NOT RECOMMENDED for general security reasons. For tel URLs, the tel and user subfields are the subscriber name; in the former case, "noise" characters are stripped. the host and port subfields are both not present. For other URI schemes, only the address-type subfield is defined by this specification; servers MAY set others of the pre-defined subfields, or MAY support additional subfields. If no subfield is specified for addresses in SIP messages, the string matched is the URI part of the address, with all parameters stripped. 4.1.2 Address switch mapping for H.323 For H.323, the origin address corresponds to the address in the sourceAddress field; both destination and original-destination correspond to the destinationAddress field, as H.323 has no indication of original destination. For all addresses in H.323 messages, the value of the address-type field is h323. The tel tag is set to the AliasAddress, if its type is e164. The user tag is set to h323-ID; host is set to transportID/TransportAddress/ipAddress, translated to a dotted-quad; port is set to transportID/TransportAddress/ipAddress/port. The display tag is not present. An additional subfield, asn1, is defined as the textually-encoded ASN.1 of the address. The matching if no subfield is specified is undefined at this time. TODO: Have this looked over by an H.323 expert for accuracy/completeness. Once an h323 URL scheme is defined, it should be used for the whole-address matching. Lennox/Schulzrinne [Page 10] Internet Draft CPL March 10, 2000 4.2 String switches String switches allow a CPL script to make decisions based on free- form Unicode strings present in a call request. They are summarized in figure 5. Node: string-switch Outputs: string Specific string to match Parameters: field subject, organization, or user-agent Output: string Parameters: is exact match contains substring match Figure 5: Syntax of the string-switch node String switches have one node parameter: field. The mandatory field parameter specifies which string is to be matched. Currently three fields are defined: subject, indicating the subject of the call; organization, indicating the originator's organization; and user- agent, indicating the program or device with which the call request was made. All these fields correspond to SIP strings. TODO: Need H.323 free-form strings. "Data"? Strings are matched as case-insensitive Unicode strings, in the following manner. First, strings are canonicalized to the "Compatibility Composition" (KC) form, as specified in Unicode Technical Report 15 [8]. Then, strings are compared using locale- insensitive caseless mapping, as specified in Unicode Technical Report 21 [9]. Code to perform the first step, in Java and Perl, is available; see the links from Annex E of UTR 15 [8]. The case-insensitive string comparison in the Java standard class libraries already performs the second step; other Unicode-aware libraries should be similar. The output tags of string matching are named string, and have a mandatory argument, one of is or contains, indicating whole-string match or substring match, respectively. Lennox/Schulzrinne [Page 11] Internet Draft CPL March 10, 2000 4.3 Time switches Time switches allow a CPL script to make decisions based the time and/or date the script is being executed. They are summarized in figure 6. Node: time-switch Outputs: time Specific time to match Parameters: timezone local, utc, or other (see section 9) Output: time Parameters: year Years to match month Months to match date Days of month to match weekday Days of week to match timeofday Times of day to match Figure 6: Syntax of the time-switch node Time switches take one optional parameter, timezone, which specifies the time zone in which matching is to take place. Two values of this are predefined: local indicates the time zone in which the server is located, and utc indicates Universal Coordinated Time. Timezones may also be specified in the ancillary information; see section 9. The time outputs can take the following optional parameters: year, month, date, day, and timeofday. Each argument is syntactically expressed as a list of numeric ranges. Ranges are delimited as value-value; lists elements are separated by commas. Months are specified in the range 1-12; date as 1-31, day as 0-6 (where 0 is Sunday), and times of day as 24-hour times in the range 0000-2359; years are unlimited in range, though only positive values are allowed. An output node matches if the time the triggering call was placed falls within one of specified the ranges in each of the specified parameters. The following examples show sample time nodes, and descriptions of the corresponding time periods they indicate: