Internet DRAFT - draft-deason-sip-soap
draft-deason-sip-soap
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
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
SOAPENV:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetCreditStatus xmlns:m=
"http://www.ubiquity.net/sipservices">
<user>sip:jo@ubiquity.net</user>
</m:GetCreditStatus>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
SOAP-ENV:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetCreditStatus xmlns:m=
"http://www.ubiquity.net/sipservices">
<return>34.5</return>
</m:GetCreditStatus>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
SOAP-ENV:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetCreditStatus xmlns:m=
"http://www.there.com/services">
<user>sip:jo@ubiquity.net</user>
</m:GetCreditStatus>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
SOAP-ENV:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<m:GetCreditStatus xmlns:m=
"http://www.ubiquity.net/sipservices">
<user>sip:jo@gods.org</user>
</m:GetCreditStatus>
Deason [Page 7]
Internet Draft SIP and SOAP June 2000
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope"
SOAP-ENV:encodingStyle=
"http://schemas.xmlsoap.org/soap/encoding/" >
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>404</faultcode>
<faultstring>
Unknown User - sip:jo@gods.org
</faultstring>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
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]
