Internet Engineering Task Force N. Deason Internet Draft Ubiquity Software draft-deason-sip-soap-00.txt Corporation Ltd. June 30, 2000 Expires December 2000 SIP and SOAP 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. 1. Abstract This document describes an extension to the Session Initiation Protocol (SIP) [1] . The purpose of this extension is to provide an extremely generic and extensible framework through which SIP nodes can request additional services from remote nodes. Examples of such nodes include SIP Network Servers, SIP User Agents, SIP/PSTN Gateways, SIP/H.323 Gateways and SIP Enabled Application Service Brokers. It also a candidate for providing a remote procedure call mechanism for Call Processing Language (CPL) scripts [2] . This proposal is based upon a new SIP method, called SERVICE. The SERVICE method can carry a Simple Object Access Protocol (SOAP) [3] message as it's payload. SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. SOAP defines a framework for encoding request and response messages in XML. Typically SOAP uses HTTP as a transport protocol but this proposal enables SIP to be used instead. 2. Conventions used in this document Deason [Page 1] Internet Draft SIP and SOAP June 2000 In examples, "C:" and "S:" indicate lines sent by the client and server respectively. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [4]. 3. Introduction Many SIP enabled network components will need to collaborate in the creation of future services. As well as the core SIP components of User Agents, Proxy Servers and Redirect Servers, there are SIP/H.323 gateways, SIP/PSTN gateways and SIP based Application Service Brokers (ASBs). Empowering these components with a generic and flexible way, within SIP, to request additional services of each other provides a basis for sophisticated service creation. It is also noted that the requirements for Call Processing Language identifies a clean interface for scripts to remote procedure calls, for instance to access an external billing database, as desirable. While Corba, RMI, or DCOM are given as possible candidates the mechanism described here is equally suitable and has the attraction of reusing SIP signaling. SOAP is a protocol specification for invoking methods on servers, services, components and objects. SOAP defines a XML vocabulary for encoding requests and responses messages and typically uses HTTP as a transport protocol. However, the definition of the XML vocabulary is entirely independent of the fact that it is usually carried over HTTP. SOAP implementations that use SMTP instead of HTTP already exist. The SOAP XML vocabulary can be used to represent method parameters, return values, and exceptions. It has been designed to be highly extensible. Like SIP, SOAP can be implemented in any language that supports text processing and is platform agnostic. As SIP shares much in common with HTTP it is relatively simple for SIP to be used as the transport protocol for SOAP requests and responses. All that is required is an additional SIP method defined here; "SERVICE". As this proposed extension is, by intention, highly flexible the question of when it's use is appropriate must be carefully considered by implementers. It should not be used to duplicate functionality that already exists within SIP. For example, a SIP node can inform another node about user location through an INVITE/3XX transaction. There is no need for a SERVICE request to be issued to implement this form of basic user location service between SIP nodes. Similarly SERVICE requests should not be used to tackle problems that lie outside of SIP's solution space. SIP's solution space has been defined within the guidelines to extending SIP [5]. Implementers should also recognise that SIP is not designed to provide the basis for a high efficiency or general computing RPC mechanism. Deason [Page 2] Internet Draft SIP and SOAP June 2000 4. The SERVICE Method The SERVICE method can be used by a SIP client to request a service of a SIP server. It is a standard SIP message and will be forwarded until it reaches the server or end user which is performing the service. The SERVICE method body is typically of the type text/xml and contains a description of the service request in the form of a SOAP request message. As the body of SIP messages are opaque other payloads are possible. The response to the SERVICE request follows the standard SIP response codes. 200-class responses indicate success, 300 redirection to an alternate server, 400 client error, 500 server error, and 600 global failure. Responses MAY contain a message body also of the type text/xml representing results of the service request described by a SOAP response message. The request message must contain a Request-URI plus To, From, Call- ID, Via, and CSeq fields. The Request-URI contains the destination of the SERVICE request. The To field contains the address of the service provider, and the From field contains the address of the service requester. All SERVICE requests from the same Client SHOULD use the same Call-ID, at least within the same reboot cycle. SERVICE request with the same Call-ID MUST have increasing CSeq header values. However, the server does not have to reject out-of-order requests. As the SERVICE request has no direct effect on any existing call state it represents a new Call leg. If information relating to en existing Call leg or SIP transaction is required to complete the service request it should be sent with the SOAP message. All of the SIP general headers, Date, Encryption, Expires, Organization may be present and retain the same meaning as they do in SIP. All the request headers also have the same semantics as in SIP. The entity headers are used to describe the XML payload containing the SOAP message, or any other type of payload, if present. This table expands on tables 4 and 5 in RFC 2543 [1]. Header Where SERV ------ ----- ---- Accept R o Accept 415 o Accept r o Accept-Encoding R o Accept-Encoding 415 o Accept-Language R o Accept-Language 415 o Allow 200 o Allow 405 m Authorization R o Authorization r o Call-ID gc m Contact R o Deason [Page 3] Internet Draft SIP and SOAP June 2000 Contact 1xx o Contact 2xx o Contact 3xx o Contact 485 o Content-Disposition e o Content-Encoding e o Content-Function e o Content-Language e m Content-Length e m Content-Type e * CSeq gc m Date g o Encryption g o Expires g o From gc m Hide R o In-Reply-To R - Max-Forwards R o MIME-Version g o Organization g o Priority R o Proxy-Authenticate 407 o Proxy-Authorization R o Proxy-Require R o Record-Route R o Record-Route 2xx,401,484 o Require g o Response-Key R o Retry-After R - Retry-After 404,413,480,486 o Retry-After 500,503 o Retry-After 600,603 o Route R o Server r o Subject R - Supported g o Timestamp g o To gc(1) m Unsupported R o Unsupported 420 o User-Agent g o Via gc(2) m Warning r o WWW-Authenticate R o WWW-Authenticate 401 o Table 1. Summary of header fields. (1) copied with possible addition of tags; (2) UAS removes first Via header field. It is generally anticipated that a SERVICE request will be sent from a SIP Client to a well known destination SIP Server that it expects to be able to support the method. If this is not the case the Client can probe a Server for support of the SERVICE method by sending an Deason [Page 4] Internet Draft SIP and SOAP June 2000 OPTIONS request. The response to this request should contain the Allow header entity-field listing the set of supported methods. If the token SERVICE included in this field the method is supported. 5. SOAP Messages As detailed descriptions of how a SOAP message encodes a service request, and the results of service requests in a response, exist elsewhere [3] this section only provides an overview. The SOAP message component is made up of a XML document containing a mandatory SOAP envelope, an optional SOAP header, and a mandatory SOAP body. This can be carried within the SIP message body of type text/xml. The SOAP envelope is the top element of the XML document. The SOAP header is a generic mechanism for adding features to a SOAP message. SOAP provides a few attributes to indicate who should deal with a feature and whether it is mandatory or optional. In this way features can be added without prior agreement between the communicating parties. Extensions that could be implemented as header entries include transaction management, payment, specific method versioning, QoS specification etc. The SOAP body is a container for all mandatory information intended for the ultimate recipient of the SOAP message. The encoding rules for this information are well defined. SOAP also defines a Fault element that can be used in the SOAP body for reporting errors. The SOAP encoding style is based on a simple type system that is a generalisation of the common features found in type systems in programming languages, databases and semi-structured data. A type is either a simple (scalar) type or is a compound type constructed as a composite of several parts, each with a type. This allows the encoding of simple types (e.g. int, float, string), enumerations, arrays, compound values, structs and references to values. It is worth noting that it is possible to use other encoding styles that specify different serialization rules within a SOAP message. The SOAP encodingStyle global attribute can be used to indicate the encoding style being used. 6. Examples The following section illustrates example call flows. It uses a trivial credit check service that could be implemented using the the SIP SERVICE method to make SOAP requests. This example is modeled on Example 1 from the SOAP Protocol proposal [3]. As such it is an example designed to aid understanding of the SOAP messages rather than illustrate a meaningful service. The first example shows a successful response to a service request. Deason [Page 5] Internet Draft SIP and SOAP June 2000 C->S: SERVICE sip:application_service_broker.ubiquity.net SIP/2.0 To: sip:application_service_broker.ubiquity.net From: sip:proxy.ubiquity.net Call-ID:648324@193.195.52.30 CSeq: 1 SERVICE Via: SIP/2.0/UDP proxy.ubiquity.net Content-Type: text/xml Content-Length: 381 sip:jo@ubiquity.net S->C: SIP/2.0 200 OK To: sip:application_service_broker.ubiquity.net From: sip:proxy.ubiquity.net Call-ID:648324@193.195.52.30 CSeq: 1 SERVICE Via: SIP/2.0/UDP proxy.ubiquity.net Content-Type: text/xml Content-Length: 371 34.5 The next example shows an unsuccessful call flow where the application service does not support the requested service. C->S: SERVICE sip:application_service_broker.there.com SIP/2.0 Deason [Page 6] Internet Draft SIP and SOAP June 2000 To: sip:application_service_broker.there.com From: sip:proxy.here.com Call-ID:648324@112.33.58.22 CSeq: 1 SERVICE Via: SIP/2.0/UDP proxy.here.com Content-Type: text/xml Content-Length: 376 sip:jo@ubiquity.net S->C: SIP/2.0 501 Not Implemented To: sip:application_service_broker.there.com From: sip:proxy.here.com Call-ID:648324@112.33.58.22 CSeq: 1 SERVICE Via: SIP/2.0/UDP proxy.here.com The final example illustrates the call flow when the requested service is unsuccessful. C->S: SERVICE sip:application_service_broker.ubiquity.net SIP/2.0 To: sip:application_service_broker.ubiquity.net From: sip:proxy.ubiquity.net Call-ID:648324@193.195.52.30 CSeq: 1 SERVICE Via: SIP/2.0/UDP proxy.ubiquity.net Content-Type: text/xml Content-Length: 400 sip:jo@gods.org Deason [Page 7] Internet Draft SIP and SOAP June 2000 S->C: SIP/2.0 500 Server Internal Error To: sip:application_service_broker.ubiquity.net From: sip:proxy.ubiquity.net Call-ID:648324@193.195.52.30 CSeq: 1 SERVICE Via: SIP/2.0/UDP proxy.ubiquity.net Content-Type: text/xml Content-Length: 418 404 Unknown User - sip:jo@gods.org 7. Security Considerations This extension does not require any security capabilities to be added to SIP. It is expected that both authentication and encryption as already described by SIP will be of high importance to implementers. 8. References 1 M. Handley, H. Schulzrinne, E. Schooler, and J. Rosenberg, "SIP: Session Initiation Protocol" Request for Comments (Proposed Standard) 2543, Internet Engineering Task Force, Mar. 1999 2 J. Lennox and H. Schulzrinne, "Call Processing Language Framework and Requirements" Request for Comments (Informational) 2824, Internet Engineering Task Force, May 2000 3 D. Box, D. Ehnebuske, G. Kakivaya, A. Layman, N. Mendelsohn, H. Nielsen, S. Thatte, and D. Winer, " Simple Object Access Protocol (SOAP) 1.1", W3C Note 08 May 2000, http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ Deason [Page 8] Internet Draft SIP and SOAP June 2000 4 Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997 5 J. Rosenberg and H. Schulzrinne, "Guidelines for Authors of SIP Extensions", Internet Draft, Internet Engineering Task Force, March 2000. Work in progress 9. Acknowledgments I would like to thank the authors of both SIP and SOAP for their hard work. Jo Hornsby and James Undery of Ubiquity Software for their useful discussions and comments. 10. Author's Addresses Neil Deason Ubiquity Software Corporation Limited Ubiquity House Langstone Park Newport South Wales United Kingdom NP18 2LH email: ndeason@ubiquity.net Full Copyright Statement "Copyright (C) The Internet Society (2000). 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." Deason [Page 9]