Network Working Group R. Sparks
Internet-Draft dynamicsoft
Expires: April 30, 2002 October 30, 2001
The Refer Method
draft-ietf-sip-refer-02
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.
This Internet-Draft will expire on April 30, 2002.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract
This document defines the REFER method. This SIP extension requests
that the recipient REFER to a resource provided in the request. This
can be used to enable many applications, including Call Transfer.
Sparks Expires April 30, 2002 [Page 1]
Internet-Draft The Refer Method October 2001
Table of Contents
1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Changes from draft-ietf-sip-refer-01 . . . . . . . . . . . 3
3. The REFER Method . . . . . . . . . . . . . . . . . . . . . 3
3.1 The Refer-To Header . . . . . . . . . . . . . . . . . . . 3
3.1.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2 The Referred-By Header . . . . . . . . . . . . . . . . . . 4
3.2.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.3 Header Field Support for the REFER Method . . . . . . . . 5
3.4 Message Body Inclusion . . . . . . . . . . . . . . . . . . 6
3.5 Behavior of SIP User Agents . . . . . . . . . . . . . . . 6
3.5.1 Accessing the referred-to resource . . . . . . . . . . . . 6
3.5.2 UA Responses within the REFER transaction . . . . . . . . 6
3.5.3 Reporting on the results of the reference . . . . . . . . 7
3.5.3.1 Using NOTIFY . . . . . . . . . . . . . . . . . . . . . . . 7
3.5.3.2 The body of the NOTIFY . . . . . . . . . . . . . . . . . . 7
3.5.3.3 Multiple REFER requests in a dialog . . . . . . . . . . . 8
3.6 Behavior of SIP Registrars/Redirect Servers . . . . . . . 9
3.7 Behavior of SIP Proxies . . . . . . . . . . . . . . . . . 9
3.8 Examples . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.8.1 Prototypical REFER callflow . . . . . . . . . . . . . . . 9
3.8.2 Multiple REFERs in a dialog . . . . . . . . . . . . . . . 11
3.9 Security Considerations . . . . . . . . . . . . . . . . . 12
3.9.1 Circumventing privacy . . . . . . . . . . . . . . . . . . 13
3.9.2 Circumventing security . . . . . . . . . . . . . . . . . . 13
3.9.3 Limiting the breach . . . . . . . . . . . . . . . . . . . 13
4. Historic Material . . . . . . . . . . . . . . . . . . . . 14
5. IANA Considerations . . . . . . . . . . . . . . . . . . . 14
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 14
References . . . . . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . 15
Full Copyright Statement . . . . . . . . . . . . . . . . . 16
Sparks Expires April 30, 2002 [Page 2]
Internet-Draft The Refer Method October 2001
1. Overview
This document defines the REFER method. This SIP SIP [1] extension
requests that the recipient REFER to a resource provided in the
request. This can be used to enable many applications, including
Call Transfer.
2. Changes from draft-ietf-sip-refer-01
o Adopted the dialog terminology
o Added a mechanism to deal with more than one REFER within a
dialog.
o Fixed a bug in the document source that caused the IANA section in
01 to be blank
o Corrected various syntax bugs in examples
3. The REFER Method
REFER is a SIP method as defined by RFC2543 [1]. The REFER method
indicates that the recipient (identified by the Request-URI) should
contact a third party using the contact information provided in the
method. A success response indicates that the recipient was able to
contact the third party.
Unless stated otherwise, the protocol for emitting and responding to
a REFER request are identical to those for a BYE request in [1]. The
behavior of SIP entities not implementing the REFER (or any other
unknown) method is explicitly defined in [1].
A REFER request MAY be placed outside the scope of a dialog created
with an INVITE. REFER MAY be Record-Routed, hence MUST contain a
single Contact header. REFERs occurring inside an existing dialog
MUST follow the Route/Record-Route logic of that dialog. REFERs
occurring outside an existing dialog effectively create a new dialog
following the behavior of SUBSCRIBE specified [2].
3.1 The Refer-To Header
Refer-To is a request-header as defined by [1]. It may only appear
in a REFER request. It provides a URL to reference.
Refer-To = ("Refer-To" | "r") ":" URL
Sparks Expires April 30, 2002 [Page 3]
Internet-Draft The Refer Method October 2001
A REFER method MUST contain exactly one Refer-To header.
The Refer-To header MAY be encrypted as part of end-end encryption.
The Contact header is an important part of the Route/Record-Route
mechanism and is not available to be used to indicate the target of the
reference.
3.1.1 Examples
Refer-To: sip:alice@atlanta.com
Refer-To: sip:bob@biloxi.com?Accept-Contact=sip:bobsdesk.
biloxi.com&Call-ID=55432%40alicepc.atlanta.com
Refer-To: sip:dave@denver.com?Replaces:12345%40192.168.118.3;
to-tag=12345;from-tag=5FFE-3994;
Refer-To: sip:carol@cleveland.com;method=SUBSCRIBE
Refer-To: http://www.ietf.org
Long headers are line-wrapped here for clarity only.
3.2 The Referred-By Header
Referred-By is a request-header as defined by [1]. It can appear in
any request. It conveys the identity of the original REFERrer to the
referred-to party.
Referred-By = ("Referred-By" | "b") ":" referrer-url
*( ";" generic-param )
referrer-url = ( name-addr | addr-spec )
The referrer-url contains the SIP URL of the party sending the REFER
request.
A REFER request MUST contain exactly one Referred-By header.
The Referred-By header MAY be encrypted as part of end-end
encryption.
Sparks Expires April 30, 2002 [Page 4]
Internet-Draft The Refer Method October 2001
3.2.1 Examples
Referred-By: sip:alice@atlanta.com
Referred-By: "Bob" <sip:bob@biloxi.com>
3.3 Header Field Support for the REFER Method
This table adds a column to tables 4 and 5 in [1], describing header
presence in a REFER method. See [1] for a key for the symbols used.
A row for the Refer-To: and Referred-By request-header should be
inferred, each mandatory for REFER. Refer-To is not applicable for
any other methods. Referred-By is a general Request header. The enc
and e-e columns in [1] apply to the REFER method unmodified.
Header Where REFER
Accept R o
Accept-Encoding R o
Accept-Language R o
Allow R o
Allow 405 m
Authorization R o
Call-ID gc m
Contact R m
Contact 1xx -
Contact 2-6xx o
Content-Encoding e o
Content-Length e o
Content-Type e o
CSeq gc m
Date g o
Encryption g o
Expires R o
From gc m
Hide R o
Max-Forwards R o
Organization g o
Priority R -
Proxy-Authenticate 407 o
Proxy-Authorization R o
Proxy-Require R o
Require R o
Retry-After R -
Retry-After 404,480,486 o
Retry-After 503 o
Sparks Expires April 30, 2002 [Page 5]
Internet-Draft The Refer Method October 2001
Retry-After 600,603 o
Response-Key R o
Record-Route R o
Record-Route 2xx o
Route R o
Server r o
Subject R -
Timestamp g o
To gc(1) m
Unsupported 420 o
User-Agent g o
Via gc(2) m
Warning r o
WWW-Authenticate 401 o
Table 1: Header Field Support
3.4 Message Body Inclusion
A REFER method MAY contain a body. This specification assigns no
meaning to such a body. A receiving agent may choose to process the
body according to its Content-Type.
3.5 Behavior of SIP User Agents
3.5.1 Accessing the referred-to resource
A UA accepting a well-formed REFER request SHOULD request approval
from the user to proceed (this request could be interactive or
through configuration). Upon receiving approval from the user, the
UA MUST contact the resource identified by the URL in the Refer-To:
header. Note that if the URL is a SIP URL, it could contain header
fields such as Call-Id that may be used to form the resulting
request. If the URL is a SIP URL, the Referred-By header in the
REFER request should be copied into the request sent to the referred-
to resource.
The resource identified by the Refer-To: URL is contacted using the
normal mechanisms for that URL type. For example, if the URL is a
SIP INVITE URL, the UA would issue a new INVITE using all of the
normal rules for sending an INVITE defined in [1].
3.5.2 UA Responses within the REFER transaction
If the recipient's user agent receives a well formed REFER request
and decides to contact the resource in the Refer-To header, a 202
Accepted response MUST be returned before the REFER transaction
Sparks Expires April 30, 2002 [Page 6]
Internet-Draft The Refer Method October 2001
expires.
An agent responding to a REFER Method MUST return a 400 Bad Request
if the request contained zero or more than one Refer-To headers.
An agent responding to a REFER Method MUST return a 400 Bad Request
if the request contained zero or more than one Referred-By headers.
An agent (including proxies generating local responses) MAY return a
100 Trying or any appropriate 400-600 class response as prescribed by
[1].
3.5.3 Reporting on the results of the reference
3.5.3.1 Using NOTIFY
Once it is known whether the reference succeeded or failed, the UA
receiving the REFER SHOULD notify the agent sending the refer using
the NOTIFY mechanism defined in Event Notification in SIP [2] as if
the REFER had established a subscription. In particular:
o Each NOTIFY should reflect the To:, From:, and Call-ID headers
from the REFER as if they had arrived in a SUBSCRIBE.
o Each NOTIFY MUST contain an event header of Event: refer
o Each NOTIFY MUST contain a body of type "message/sipfrag".
o Analogous to the case for SUBSCRIBE described in [2], the agent
that issued the REFER MUST be prepared to receive a NOTIFY before
the REFER transaction completes.
3.5.3.2 The body of the NOTIFY
Each NOTIFY MUST contain a body of type "message/sipfrag" (see IANA).
The body of a NOTIFY MUST begin with a SIP Response Status-Line as
defined in [1]. The response class in this status line indicates the
success of the referred action. The body MAY contain other SIP
headers to provide information about the outcome of the referenced
action.
A minimal, but complete, implementation can respond with a single
Sparks Expires April 30, 2002 [Page 7]
Internet-Draft The Refer Method October 2001
NOTIFY containing either the body:
SIP/2.0 200 OK
if the reference was successful or the body:
SIP/2.0 503 Service Unavailable
if the reference failed.
An implementation MAY include more of a SIP message in that body to
convey more information. Warning headers received in responses to
the referred action are good candidates. In fact, if the reference
was to a SIP URL, the entire response to the referenced action could
be returned (perhaps to assist with debugging). However, doing so
could have grave security repercussions (see Section 3.9).
Implementers must carefully consider what they choose to include.
Note that if the reference was to a non-SIP URL, status in any
NOTIFYs to the referrer must still be in the form of SIP Response
Status-Lines. The minimal implementation discussed above is
sufficient to provide a basic indication of success or failure. For
example, if a client receives a REFER to a HTTP URL, and is
successful in accessing the resource, its NOTIFY to the referrer can
contain the message/sipfrag body of "SIP/2.0 200 OK". If the
notifier wishes to return additional non-SIP protocol specific
information about the status of the request, it may place it in the
body of the sipfrag message.
3.5.3.3 Multiple REFER requests in a dialog
A REFER creates an implicit subscription sharing the dialog
identifers in the REFER request. If more than one REFER is issued in
the same dialog (a second attempt at transferring a call for
example), the dialog identifiers do not provide enough information to
associate the resulting NOTIFYs with the proper REFER.
Thus, for the second and subsequent REFER requests a UA receives in a
given dialog, it MUST include a cseq parameter in the Event header
field of each NOTIFY containing the sequence number of the REFER this
NOTIFY is associated with.
cseqparam = "cseq" EQUAL 1*DIGIT
Sparks Expires April 30, 2002 [Page 8]
Internet-Draft The Refer Method October 2001
Where EQUAL is the character "=" surrounded by an arbitrary amount of
whitespace and DIGIT is defined as in RFC~2543.
3.6 Behavior of SIP Registrars/Redirect Servers
Registrars and Redirect Servers SHOULD return a 603 to a REFER
request, unless they are also playing some other SIP role.
3.7 Behavior of SIP Proxies
SIP Proxies do not require modification to support the REFER method.
Specifically, as required by [1], a proxy should process a REFER
request the same way it processes an OPTIONS request.
3.8 Examples
3.8.1 Prototypical REFER callflow
Agent A Agent B
| |
| F1 REFER |
|----------------------->|
| F2 202 Accepted |
|<-----------------------|
| |
| |------->
| | (whatever)
| |<------
| |
| F3 NOTIFY |
|<-----------------------|
| F4 200 OK |
|----------------------->|
| |
| |
Here are examples of what the four messages between Agent A and Agent
B might look like if the reference to (whatever) that Agent B makes
is successful. The details of this flow indicate this particular
REFER occurs outside a session (there is no To: tag in the REFER
request). If the REFER occurs inside a session, there would be a
non-empty To: tag in the request.
Message One (F1)
Sparks Expires April 30, 2002 [Page 9]
Internet-Draft The Refer Method October 2001
REFER sip:b@agentland SIP/2.0
Via: SIP/2.0/UDP agenta.agentland
To: <sip:b@agentland>
From: <sip:a@agentland>;tag=193402342
Call-ID: 898234234@agenta.agentland
CSeq: 93809823 REFER
Refer-To: (whatever URL)
Referred-By: <sip:a@agentland>
Contact: sip:a@agentland
Content-Length: 0
Message Two (F2)
SIP/2.0 202 Accepted
Via: SIP/2.0/UDP agenta.agentland
To: <sip:b@agentland>;tag=4992881234
From: <sip:a@agentland>;tag=193402342
Call-ID: 898234234@agenta.agentland
CSeq: 93809823 REFER
Contact: sip:b@agentland
Content-Length: 0
Message Three (F3)
NOTIFY sip:a@agentland SIP/2.0
Via: SIP/2.0/UDP agentb.agentland
To: <sip:a@agentland>;tag=193402342
From: <sip:b@agentland>;tag=4992881234
Call-ID: 898234234@agenta.agentland
CSeq: 1993402 NOTIFY
Event: refer
Contact: sip:b@agentland
Content-Type: message/sipfrag;version=2.0
Content-Length: 16
SIP/2.0 200 OK
Message Four (F4)
SIP/2.0 200 OK
Via: SIP/2.0/UDP agentb.agentland
To: <sip:a@agentland>;tag=193402342
From: <sip:b@agentland>;tag=4992881234
Call-ID: 898234234@agenta.agentland
CSeq: 1993402 NOTIFY
Contact: sip:a@agentland
Content-Length: 0
Sparks Expires April 30, 2002 [Page 10]
Internet-Draft The Refer Method October 2001
3.8.2 Multiple REFERs in a dialog
Message One above brings an implicit subscription dialog into
existance. Suppose Agent A issued a second REFER inside that dialog:
Agent A Agent B
| |
| F5 REFER |
|----------------------->|
| F6 202 Accepted |
|<-----------------------|
| |
| |------->
| | (something different)
| |<------
| |
| F7 NOTIFY |
|<-----------------------|
| F8 200 OK |
|----------------------->|
| |
| |
Message Five (F5)
REFER sip:b@agentland SIP/2.0
Via: SIP/2.0/UDP agenta.agentland
To: <sip:b@agentland>;tag=4992881234
From: <sip:a@agentland>;tag=193402342
Call-ID: 898234234@agenta.agentland
CSeq: 93809824 REFER
Refer-To: (some different URL)
Referred-By: <sip:a@agentland>
Contact: sip:a@agentland
Content-Length: 0
Message Six (F6)
SIP/2.0 202 Accepted
Via: SIP/2.0/UDP agenta.agentland
To: <sip:b@agentland>;tag=4992881234
From: <sip:a@agentland>;tag=193402342
Call-ID: 898234234@agenta.agentland
CSeq: 93809824 REFER
Contact: sip:b@agentland
Content-Length: 0
Message Seven (F7)
Sparks Expires April 30, 2002 [Page 11]
Internet-Draft The Refer Method October 2001
NOTIFY sip:a@agentland SIP/2.0
Via: SIP/2.0/UDP agentb.agentland
To: <sip:a@agentland>;tag=193402342
From: <sip:b@agentland>;tag=4992881234
Call-ID: 898234234@agenta.agentland
CSeq: 1993403 NOTIFY
Event: refer;cseq=93809824
Contact: sip:b@agentland
Content-Type: message/sipfrag;version=2.0
Content-Length: 16
SIP/2.0 200 OK
Message Eight (F8)
SIP/2.0 200 OK
Via: SIP/2.0/UDP agentb.agentland
To: <sip:a@agentland>;tag=193402342
From: <sip:b@agentland>;tag=4992881234
Call-ID: 898234234@agenta.agentland
CSeq: 1993403 NOTIFY
Contact: sip:a@agentland
Content-Length: 0
3.9 Security Considerations
The security requirements of [1] apply to the REFER method.
Until a security mechanism for protecting header integrity,
particularly when that header has been copied into other messages, is
agreed upon in SIP, anyone can issue a request claiming that they
were referred to that resource by an arbitrary third party.
This mechanism relies on providing contact information for the
referred-to resource to the party being referred. Care should be
taken to provide a suitably restricted URI if the referred to
resource should be protected.
Care should be taken when implementing the logic that determines
whether or not to accept the REFER request. A UA not capable of
accessing non-SIP URLs SHOULD NOT accept REFER requests to them.
Using message/sipfrag bodies to return the progress and results of a
REFER request is extremely powerful. Careless use of that capability
will compromise security and privacy. Here are a couple of simple,
somewhat contrived, examples to demonstrate the potential for harm.
Sparks Expires April 30, 2002 [Page 12]
Internet-Draft The Refer Method October 2001
3.9.1 Circumventing privacy
Suppose Alice has a user-agent that accepts REFER requests to SIP
INVITE URLs, and NOTIFYs the referrer of the progress of the INVITE
by copying each response to the INVITE into the body of a NOTIFY.
Suppose further that Carol has a reason to avoid Mallory and has
configured her system at her proxy to only accept calls from a
certain set of people she trusts (including Alice), so that Mallory
doesn't learn when she's around, or what user agent she's actually
using.
Mallory can send a REFER to Alice, with a Refer-To: indicating Carol.
If Alice can reach Carol, the 200 OK Carol sends gets returned to
Mallory in a NOTIFY, letting him know not only that Carol is around,
but also the IP address of the agent she's using.
3.9.2 Circumventing security
Suppose Alice, with the same user agent as above, is working at a
company that is working on the greatest SIP device ever invented -
the SIP FOO. The company has been working for months building the
device and the marketing materials, carefully keeping the idea, even
the name of the idea secret (since a FOO is one of those things that
anybody could do if they'd just had the idea first). FOO is up and
running, and anyone at the company can use it, but it's not available
outside the company firewall.
Mallory has heard rumor that Alice's company is onto something big,
and has even managed to get his hands on a URL that he suspects might
have something to do with it. He sends a REFER to ALICE with the
mysterious URL and as Alice connects to the FOO, Mallory gets NOTIFYs
with bodies containing
Server: FOO/v0.9.7
3.9.3 Limiting the breach
For each of these cases, and in general, returning a carefully
selected subset of the information available about the progress of
the reference through the NOTIFYs mitigates risk. The minimal
implementation described in Section 3.5.3.2 exposes the least
information about what the agent operating on the REFER request has
done, and is least likely to be a useful tool for malicious users.
Sparks Expires April 30, 2002 [Page 13]
Internet-Draft The Refer Method October 2001
4. Historic Material
This method was initially motivated by the call-transfer application.
Starting as TRANSFER, and later generalizing to REFER, this method
improved on the BYE/Also concept of the expired draft-ietf-sip-cc-01
by disassociating transfers from the processing of BYE. These
changes facilitate recovery of failed transfers and clarify state
management in the participating entities.
Earlier versions of this work required the agent responding to REFER
to wait until the referred action completed before sending a final
response to the REFER. That final response reflected the success or
failure of the referred action. This was infeasible due to the
transaction timeout rules defined for non-INVITE requests in [1]. A
REFER must always receive an immediate (within the lifetime of a non-
INVITE transaction) final response.
During the evolution of this specification, the Referred-By header
optionally contained a copy of the referrenced URL and a signature
over the referrer-url and referrenced URL so that the refer target
had a mechanism to verify that a request it received actually
happened as a result of a REFER to its particular URL. This
mechanism was removed in anticipation of using the more general
security mechanisms being developed in SIP.
5. IANA Considerations
This document defines a new SIP method name (REFER), two new SIP
header names with compact forms (Refer-To and Referred-By) and an
Event header parameter (cseq). These identities should be tracked as
sip-parameters.
6. Acknowledgments
This draft is a collaborative product of the SIP working group.
References
[1] Handley, M., Schulzrinne, H., Schooler, E. and J. Rosenberg,
"SIP: Session Initiation Protocol", RFC 2543, March 1999.
[2] Roach, A., "SIP-Specific Event Notification", draft-sip-events-
00 (work in progress), July 2001.
Sparks Expires April 30, 2002 [Page 14]
Internet-Draft The Refer Method October 2001
Author's Address
Robert J. Sparks
dynamicsoft
5100 Tennyson Parkway
Suite 1200
Plano, TX 75024
EMail: rsparks@dynamicsoft.com
Sparks Expires April 30, 2002 [Page 15]
Internet-Draft The Refer Method October 2001
Full Copyright Statement
Copyright (C) The Internet Society (2001). 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 languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS 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.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Sparks Expires April 30, 2002 [Page 16]
