[Search] [txt|pdf|bibtex] [Tracker] [WG] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 rfc3515                               
Network Working Group                                          R. Sparks
Internet-Draft                                               dynamicsoft
Expires: January 16, 2002                                  July 18, 2001


                            The Refer Method
                       draft-ietf-sip-refer-00.txt

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 January 16, 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 January 16, 2002                [Page 1]


Internet-Draft              The Refer Method                   July 2001


Table of Contents

   1.      Overview . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.      Changes from draft-sparks-sip-cc-transfer-04 . . . . . . .  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   A PGP based signature-scheme . . . . . . . . . . . . . . .  5
   3.2.2   Examples . . . . . . . . . . . . . . . . . . . . . . . . .  5
   3.3     Header Field Support for the REFER Method  . . . . . . . .  5
   3.4     Message Body Inclusion . . . . . . . . . . . . . . . . . .  7
   3.5     Responses within the REFER transaction . . . . . . . . . .  7
   3.6     Behavior of SIP User Agents  . . . . . . . . . . . . . . .  7
   3.6.1   Accessing the referred-to resource . . . . . . . . . . . .  7
   3.6.2   Reporting on the results of the reference  . . . . . . . .  7
   3.6.2.1 Using NOTIFY . . . . . . . . . . . . . . . . . . . . . . .  7
   3.6.2.2 The body of the NOTIFY . . . . . . . . . . . . . . . . . .  8
   3.7     Behavior of SIP Registrars/Redirect Servers  . . . . . . .  9
   3.8     Behavior of SIP Proxies  . . . . . . . . . . . . . . . . .  9
   3.9     Prototypical REFER callflow  . . . . . . . . . . . . . . .  9
   3.10    Security Considerations  . . . . . . . . . . . . . . . . . 11
   3.10.1  Circumventing privacy  . . . . . . . . . . . . . . . . . . 11
   3.10.2  Circumventing security . . . . . . . . . . . . . . . . . . 11
   3.10.3  Limiting the breach  . . . . . . . . . . . . . . . . . . . 12
   4.      Historic Material  . . . . . . . . . . . . . . . . . . . . 12
   5.      Open Issues  . . . . . . . . . . . . . . . . . . . . . . . 12
   5.1     REFER is now dependent on sip-events . . . . . . . . . . . 12
   5.2     Registering the refer event with IANA  . . . . . . . . . . 13
   6.      Acknowledgments  . . . . . . . . . . . . . . . . . . . . . 13
           References . . . . . . . . . . . . . . . . . . . . . . . . 13
           Author's Address . . . . . . . . . . . . . . . . . . . . . 13
           Full Copyright Statement . . . . . . . . . . . . . . . . . 14


















Sparks                  Expires January 16, 2002                [Page 2]


Internet-Draft              The Refer Method                   July 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.

   Editor's note: Per working group consensus, draft-ietf-sip-cc-
   transfer-04 was split into two drafts.  This draft specifies the
   REFER method itself.  Its companion (name to be determined) details
   the use of REFER to achieve call transfer.

2. Changes from draft-sparks-sip-cc-transfer-04

   o  Split the document
   o  Simplified the expression of the Referred-By grammar
   o  Resolved inconsistency in Referred-By signature normative text and
      example

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 call-leg created
   with an INVITE.  REFER MAY be Record-Routed, hence MUST contain a
   single Contact header.  REFERs occurring inside an existing call-leg
   MUST follow the Route/Record-Route logic of that call-leg.  REFERs
   occurring outside an existing call-leg effectively create a new call-
   leg 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

   A REFER method MUST contain exactly one Refer-To header.




Sparks                  Expires January 16, 2002                [Page 3]


Internet-Draft              The Refer Method                   July 2001


   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@alicepc.atlanta.com

         Refer-To: <sip:dave@denver.com?Replaces:12345@192.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, optionally proving the identity and that the
   REFERrer actually issued this reference.



        Referred-By      = ("Referred-By" | "b") ":"
                           referrer-url [ referenced-url ]

        referrer-url     = ( name-addr | addr-spec )

        referenced-url   = ";" "ref" "=" "<" URL ">" [ ref-signature ]

        ref-signature    = ";" signature-scheme *( sig-scheme-params )

        signature-scheme = "scheme" "=" token

        sig-scheme-parms = ";" token "=" ( token | quoted-string )


   The referrer-url contains the SIP URL of the party sending the REFER
   request.  The referenced-url contains a copy of the URL placed in the



Sparks                  Expires January 16, 2002                [Page 4]


Internet-Draft              The Refer Method                   July 2001


   Refer-To: header.  Any occurrences of < or > in the referenced-url
   MUST be escaped.  The ref-signature contains a signature over the
   concatenation of addr-spec portion of the referrer-url and the entire
   referenced-url.  An example signature scheme is given in section
   Section 3.2.1.

   A REFER request MUST contain exactly one Referred-By header.

   The Referred-By header SHOULD be signed to help detection of REFERs
   from unauthorized third parties.  A signed Referred-By header SHOULD
   include a Date header in the referrer-url to facilitate detection of
   replay attacks.

   A UA MAY reject a request containing an unsigned Referred-By header.
   A UA SHOULD verify the signature on any Referred-By header it
   receives.

   The Referred-By header MAY be encrypted as part of end-end
   encryption.

3.2.1 A PGP based signature-scheme

   One signature-scheme for Referred-By headers uses PGP as follows:

        signature-scheme = "scheme" "=" "pgp"
        sig-scheme-parms = pgp-version | signed-by | pgp-signature

   pgp-version, signed-by and pgp-signature are defined in section 15.1
   of RFC2543, with the modification that the signature is computed
   across the concatenation of the addr-spec portion of the referrer-url
   and the entire referenced-url.

3.2.2 Examples


        Referred-By: sip:alice@atlanta.com;ref=<http:www.ietf.org>

        Referred-By: "Bob" <sip:bob@biloxi.com>;
           ref=<sip:alice@atlanta.com>;scheme=pgp;
           pgp-version="5.0";signature="the signature"


   (Note that in the last example, the signature would be over the
   string "sip:bob@biloxi.comsip:alice@atlanta.com")

3.3 Header Field Support for the REFER Method

   This table adds a column to tables 4 and 5 in [1], describing header



Sparks                  Expires January 16, 2002                [Page 5]


Internet-Draft              The Refer Method                   July 2001


   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       -
            Accept-Encoding             R       -
            Accept-Language             R       o
            Allow                       R       -
            Allow                      405      m
            Authorization               R       o
            Call-ID                    gc       m
            Contact                     R       m
            Contact                    1xx      -
            Contact                   2-6xx     o
            Content-Encoding            e       -
            Content-Length              e       o
            Content-Type                e       -
            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
            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



Sparks                  Expires January 16, 2002                [Page 6]


Internet-Draft              The Refer Method                   July 2001


            Warning                     r       o
            WWW-Authenticate           401      o


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 Responses within the REFER transaction

   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].  If the recipient's agent decides to contact the resource in the
   Refer-To header, a 202 Accepted response MUST be returned before the
   REFER transaction expires.

3.6 Behavior of SIP User Agents

3.6.1 Accessing the referred-to resource

   A UA receiving 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.6.2 Reporting on the results of the reference

3.6.2.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



Sparks                  Expires January 16, 2002                [Page 7]


Internet-Draft              The Refer Method                   July 2001


   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 "application/sip".  The
      contents of this body are detailed in Section 3.6.2.2

   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.6.2.2 The body of the NOTIFY

   Each NOTIFY MUST contain a body of type "application/sip".  This body
   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
   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.10).
   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



Sparks                  Expires January 16, 2002                [Page 8]


Internet-Draft              The Refer Method                   July 2001


   contain the application/sip body of "SIP/2.0 200 OK"

3.7 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.8 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.9 Prototypical REFER callflow

          Agent A                  Agent B
             |                        |
             |   REFER                |
             |----------------------->|
             |        202 Accepted    |
             |<-----------------------|
             |                        |
             |                        |------->
             |                        |  (whatever)
             |                        |<------
             |                        |
             |            NOTIFY      |
             |<-----------------------|
             |   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











Sparks                  Expires January 16, 2002                [Page 9]


Internet-Draft              The Refer Method                   July 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>;ref=<whatever URL>;
          scheme=pgp;pgp-version="5.0";signature="signature goes here"
       Contact: sip:a@agentland
       Content-Length: 0

      Message Two

       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

       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: application/sip
       Content-Length: 16

       SIP/2.0 200 OK


      Message Four











Sparks                  Expires January 16, 2002               [Page 10]


Internet-Draft              The Refer Method                   July 2001


       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


3.10 Security Considerations

   The security requirements of [1] apply to the REFER method.

   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 application/sip 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.

3.10.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.10.2 Circumventing security

   Suppose Alice, with the same user agent as above, is working at a



Sparks                  Expires January 16, 2002               [Page 11]


Internet-Draft              The Refer Method                   July 2001


   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.10.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.6.2.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.

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 now 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.

5. Open Issues

5.1 REFER is now dependent on sip-events

   This work is prevented from moving to RFC until the sip-events draft
   moves to that level.



Sparks                  Expires January 16, 2002               [Page 12]


Internet-Draft              The Refer Method                   July 2001


5.2 Registering the refer event with IANA

   When we near the end of the process, the refer event will need to be
   registered with IANA per [2].

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.


Author's Address

   Robert J. Sparks
   dynamicsoft
   5100 Tennyson Parkway
   Suite 1200
   Plano, TX  75024

   EMail: rsparks@dynamicsoft.com
























Sparks                  Expires January 16, 2002               [Page 13]


Internet-Draft              The Refer Method                   July 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 January 16, 2002               [Page 14]