RFC 5547
A Session Description Protocol (SDP) Offer/Answer Mechanism to Enable File Transfer
Network Working Group M. Garcia-Martin Request for Comments: 5547 Ericsson Category: Standards Track M. Isomaki Nokia G. Camarillo S. Loreto Ericsson P. Kyzivat Cisco Systems May 2009 A Session Description Protocol (SDP) Offer/Answer Mechanism to Enable File Transfer Status of This Memo This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited. Copyright Notice Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.Abstract
This document provides a mechanism to negotiate the transfer of one or more files between two endpoints by using the Session Description Protocol (SDP) offer/answer model specified in RFC 3264. SDP is extended to describe the attributes of the files to be transferred. The offerer can describe either the files it wants to send or the files it would like to receive. The answerer can either accept or reject the offer separately for each individual file. The transfer of one or more files is initiated after a successful negotiation. The Message Session Relay Protocol (MSRP) is defined as the default mechanism to actually carry the files between the endpoints. The conventions on how to use MSRP for file transfer are also provided in this document.
Table of Contents
1. Introduction ....................................................3 2. Terminology .....................................................4 3. Definitions .....................................................4 4. Overview of Operation ...........................................5 5. File Selector ...................................................6 6. Extensions to SDP ...............................................7 7. File Disposition Types .........................................13 8. Protocol Operation .............................................13 8.1. The 'file-transfer-id' Attribute ..........................14 8.2. Offerer's Behavior ........................................17 8.2.1. The Offerer Is a File Sender .......................17 8.2.2. The Offerer Is a File Receiver .....................18 8.2.3. SDP Offer for Several Files ........................18 8.3. Answerer's Behavior .......................................19 8.3.1. The Answerer Is a File Receiver ....................19 8.3.2. The Answerer Is a File Sender ......................20 8.4. Aborting an Ongoing File Transfer Operation ...............22 8.5. Indicating File Transfer Offer/Answer Capability ..........25 8.6. Reusage of Existing "m=" Lines in SDP .....................26 8.7. MSRP Usage ................................................26 8.8. Considerations about the 'file-icon' Attribute ............28 9. Examples .......................................................28 9.1. Offerer Sends a File to the Answerer ......................28 9.2. Offerer Requests a File from the Answerer and Second File Transfer ......................................33 9.3. Example of a Capability Indication ........................40 10. Security Considerations .......................................41 11. IANA Considerations ...........................................42 11.1. Registration of New SDP Attributes .......................42 11.1.1. Registration of the file-selector Attribute .......43 11.1.2. Registration of the file-transfer-id Attribute ....43 11.1.3. Registration of the file-disposition Attribute ....43 11.1.4. Registration of the file-date Attribute ...........44 11.1.5. Registration of the file-icon Attribute ...........44 11.1.6. Registration of the file-range Attribute ..........45 12. Acknowledgments ...............................................45 13. References ....................................................45 13.1. Normative References .....................................45 13.2. Informative References ...................................46 Appendix A. Alternatives Considered ..............................48
1. Introduction
The Session Description Protocol (SDP) offer/answer [RFC3264] provides a mechanism for two endpoints to arrive at a common view of a multimedia session between them. These sessions often contain real-time media streams such as voice and video, but are not limited to that. Basically, any media component type can be supported, as long as there is a specification how to negotiate it within the SDP offer/answer exchange. The Message Session Relay Protocol (MSRP) [RFC4975] is a protocol for transmitting instant messages (IMs) in the context of a session. The protocol specification describes the usage of SDP for establishing an MSRP session. In addition to plain text messages, MSRP is able to carry arbitrary (binary) Multipurpose Internet Mail Extensions (MIME) [RFC2045] compliant content, such as images or video clips. There are many cases where the endpoints involved in a multimedia session would like to exchange files within the context of that session. With MSRP, it is possible to embed files as MIME objects inside the stream of instant messages. MSRP also has other features that are useful for file transfer. Message chunking enables the sharing of the same transport connection between the transfer of a large file and interactive IM exchange without blocking the IM. MSRP relays [RFC4976] provide a mechanism for Network Address Translator (NAT) traversal. Finally, Secure MIME (S/MIME) [RFC3851] can be used for ensuring the integrity and confidentiality of the transferred content. However, the baseline MSRP does not readily meet all the requirements for file transfer services within multimedia sessions. There are four main missing features: o The recipient must be able to distinguish "file transfer" from "file attached to IM", allowing the recipient to treat the cases differently. o It must be possible for the sender to send the request for a file transfer. It must be possible for the recipient to accept or decline it, using the meta information in the request. The actual transfer must take place only after acceptance by the recipient. o It must be possible for the sender to pass some meta information on the file before the actual transfer. This must be able to include at least content type, size, hash, and name of the file, as well as a short (human readable) description.
o It must be possible for the recipient to request a file from the
sender, providing meta information about the file. The sender
must be able to decide whether to send a file matching the
request.
The rest of this document is organized as follows. Section 3 defines
a few terms used in this document. Section 4 provides the overview
of operation. Section 5 introduces the concept of the file selector.
The detailed syntax and semantics of the new SDP attributes and
conventions on how the existing ones are used are defined in
Section 6. Section 7 discusses the file disposition types.
Section 8 describes the protocol operation involving SDP and MSRP.
Finally, some examples are given in Section 9.
2. Terminology
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 BCP 14, RFC 2119
[RFC2119].
3. Definitions
For the purpose of this document, the following definitions specified
in RFC 3264 [RFC3264] apply:
o Answer
o Answerer
o Offer
o Offerer
Additionally, we define the following terms:
File sender: The endpoint that is willing to send a file to the file
receiver.
File receiver: The endpoint that is willing to receive a file from
the file sender.
File selector: A tuple of file attributes that the SDP offerer
includes in the SDP in order to select a file at the SDP answerer.
This is described in more detail in Section 5.
Push operation: A file transfer operation where the SDP offerer
takes the role of the file sender and the SDP answerer takes the
role of the file receiver.
Pull operation: A file transfer operation where the SDP offerer
takes the role of the file receiver and the SDP answerer takes the
role of the file sender.
4. Overview of Operation
An SDP offerer creates an SDP body that contains the description of
one or more files that the offerer wants to send or receive. The
offerer sends the SDP offer to the remote endpoint. The SDP answerer
can accept or reject the transfer of each of those files separately.
The actual file transfer is carried out using the Message Session
Relay Protocol (MSRP) [RFC4975]. Each SDP "m=" line describes an
MSRP media stream used to transfer a single file at a time. That is,
the transfer of multiple simultaneous files requires multiple "m="
lines and corresponding MSRP media streams. It should be noted that
multiple MSRP media streams can share a single transport layer
connection, so this mechanism will not lead to excessive use of
transport resources.
Each "m=" line for an MSRP media stream is accompanied with a few
attributes describing the file to be transferred. If the file sender
generates the SDP offer, the attributes describe a local file to be
sent (push), and the file receiver can use this information to either
accept or reject the transfer. However, if the SDP offer is
generated by the file receiver, the attributes are intended to
characterize a particular file that the file receiver is willing to
get (pull) from the file sender. It is possible that the file sender
does not have a matching file or does not want to send the file, in
which case the offer is rejected.
The attributes describing each file are provided in SDP by a set of
new SDP attributes, most of which have been directly borrowed from
MIME. This way, user agents can decide whether or not to accept a
given file transfer based on the file's name, size, description,
hash, icon (e.g., if the file is a picture), etc.
SDP direction attributes (e.g., 'sendonly', 'recvonly') are used to
indicate the direction of the transfer, i.e., whether the SDP offerer
is willing to send or receive the file. Assuming that the answerer
accepts the file transfer, the actual transfer of the files takes
place with ordinary MSRP. Note that the 'sendonly' and 'recvonly'
attributes refer to the direction of MSRP SEND requests and do not
preclude other protocol elements (such as 200 responses, REPORT
requests, etc.).
In principle the file transfer can work even with an endpoint
supporting only regular MSRP without understanding the extensions
defined herein, in a particular case where that endpoint is both
the SDP answerer and the file receiver. The regular MSRP endpoint
answers the offer as it would answer any ordinary MSRP offer
without paying attention to the extension attributes. In such a
scenario, the user experience would, however, be reduced, since
the recipient would not know (by any protocol means) the reason
for the session and would not be able to accept/reject it based on
the file attributes.
5. File Selector
When the file receiver generates the SDP offer, this SDP offer needs
to unambiguously identify the requested file at the file sender. For
this purpose, we introduce the notion of a file selector, which is a
tuple composed of one or more of the following individual selectors:
the name, size, type, and hash of the file. The file selector can
include any number of selectors, so all four of them do not always
need to be present.
The purpose of the file selector is to provide enough information
about the file to the remote entity, so that both the local and the
remote entity can refer to the same file. The file selector is
encoded in a 'file-selector' media attribute in SDP. The formal
syntax of the 'file-selector' media attribute is described in
Figure 1.
The file selection process is applied to all the available files at
the host. The process selects those files that match each of the
selectors present in the 'file-selector' attribute. The result can
be zero, one, or more files, depending on the presence of the
mentioned selectors in the SDP and depending on the available files
in a host. The file transfer mechanism specified in this document
requires that a file selector eventually results at most in a single
file to be chosen. Typically, if the hash selector is known, it is
enough to produce a file selector that points to exactly zero or one
file. However, a file selector that selects a unique file is not
always known by the offerer. Sometimes only the name, size, or type
of file is known, so the file selector may result in selecting more
than one file, which is an undesired case. The opposite is also
true: if the file selector contains a hash selector and a name
selector, there is a risk that the remote host has renamed the file,
in which case, although a file whose computed hash equals the hash selector exists, the file name does not match that of the name selector. Thus, in this case, the file selection process will result in the selection of zero files. This specification uses the Secure Hash Algorithm 1, SHA-1 [RFC3174]. If future needs require adding support for different hashing algorithms, they will be specified as extensions to this document. Implementations according to this specification MUST implement the 'file-selector' attribute and MAY implement any of the other attributes specified in this specification. SDP offers and answers for file transfer MUST contain a 'file-selector' media attribute that selects the file to be transferred and MAY contain any of the other attributes specified in this specification. The 'file-selector' media attribute is also useful when learning the support of the file transfer offer/answer capability that this document specifies. This is further explained in Section 8.5.6. Extensions to SDP
We define a number of new SDP [RFC4566] attributes that provide the required information to describe the transfer of a file with MSRP. These are all media-level-only attributes in SDP. The following is the formal ABNF syntax [RFC5234] of these new attributes. It is built above the SDP [RFC4566] grammar, RFC 2045 [RFC2045], RFC 2183 [RFC2183], RFC 2392 [RFC2392], and RFC 5322 [RFC5322]. attribute =/ file-selector-attr / file-disp-attr / file-tr-id-attr / file-date-attr / file-icon-attr / file-range-attr ; attribute is defined in RFC 4566 file-selector-attr = "file-selector" [":" selector *(SP selector)] selector = filename-selector / filesize-selector / filetype-selector / hash-selector filename-selector = "name:" DQUOTE filename-string DQUOTE ; DQUOTE defined in RFC 5234 filename-string = 1*(filename-char/percent-encoded) filename-char = %x01-09/%x0B-0C/%x0E-21/%x23-24/%x26-FF ; any byte except NUL, CR, LF, ; double quotes, or percent percent-encoded = "%" HEXDIG HEXDIG ; HEXDIG defined in RFC 5234 filesize-selector = "size:" filesize-value
filesize-value = integer ;integer defined in RFC 4566 filetype-selector = "type:" type "/" subtype *(";" ft-parameter) ft-parameter = attribute "=" DQUOTE value-string DQUOTE ; attribute is defined in RFC 2045 ; free insertion of linear-white-space is not ; permitted in this context. ; note: value-string has to be re-encoded ; when translating between this and a ; Content-Type header. value-string = filename-string hash-selector = "hash:" hash-algorithm ":" hash-value hash-algorithm = token ; see IANA Hash Function ; Textual Names registry ; only "sha-1" currently supported hash-value = 2HEXDIG *(":" 2HEXDIG) ; Each byte in upper-case hex, separated ; by colons. ; HEXDIG defined in RFC 5234 file-tr-id-attr = "file-transfer-id:" file-tr-id-value file-tr-id-value = token file-disp-attr = "file-disposition:" file-disp-value file-disp-value = token file-date-attr = "file-date:" date-param *(SP date-param) date-param = c-date-param / m-date-param / r-date-param c-date-param = "creation:" DQUOTE date-time DQUOTE m-date-param = "modification:" DQUOTE date-time DQUOTE r-date-param = "read:" DQUOTE date-time DQUOTE ; date-time is defined in RFC 5322 ; numeric timezones (+HHMM or -HHMM) ; must be used ; DQUOTE defined in RFC 5234 files. file-icon-attr = "file-icon:" file-icon-value file-icon-value = cid-url ; cid-url defined in RFC 2392 file-range-attr = "file-range:" start-offset "-" stop-offset start-offset = integer ; integer defined in RFC 4566 stop-offset = integer / "*" Figure 1: Syntax of the SDP extension
When used for capability query (see Section 8.5), the 'file-selector' attribute MUST NOT contain any selector, because its presence merely indicates compliance to this specification. When used in an SDP offer or answer, the 'file-selector' attribute MUST contain at least one selector. Selectors characterize the file to be transferred. There are four selectors in this attribute: 'name', 'size', 'type', and 'hash'. The 'name' selector in the 'file-selector' attribute contains the filename of the content enclosed in double quotes. The filename is encoded in UTF-8 [RFC3629]. Its value SHOULD be the same as the 'filename' parameter of the Content-Disposition header field [RFC2183] that would be signaled by the actual file transfer. If a file name contains double quotes or any other character that the syntax does not allow in the 'name' selector, they MUST be percent- encoded. The 'name' selector MUST NOT contain characters that can be interpreted as directory structure by the local operating system. If such characters are present in the file name, they MUST be percent- encoded. Note that the 'name' selector might still contain characters that, although not meaningful for the local operating system, might still be meaningful to the remote operating system (e.g., '\', '/', ':'). Therefore, implementations are responsible for sanitizing the input received from the remote endpoint before doing a local operation in the local file system, such as the creation of a local file. Among other things, implementations can percent-encode characters that are meaningful to the local operating system before doing file system local calls. The 'size' selector in the 'file-selector' attribute indicates the size of the file in octets. The value of this attribute SHOULD be the same as the 'size' parameter of the Content-Disposition header field [RFC2183] that would be signaled by the actual file transfer. Note that the 'size' selector merely includes the file size, and does not include any potential overhead added by a wrapper, such as message/cpim [RFC3862]. The 'type' selector in the 'file-selector' attribute contains the MIME media and submedia types of the content. In general, anything that can be expressed in a Content-Type header field (see RFC 2045 [RFC2045]) can also be expressed with the 'type' selectors. Possible MIME Media Type values are the ones listed in the IANA registry for MIME Media Types [IANA]. Zero or more parameters can follow. When
translating parameters from a Content-Type header and a 'type' selector, the parameter has to be re-encoded prior to its accommodation as a parameter of the 'type' selector (see the ABNF syntax of 'ft-parameter'). The 'hash' selector in the 'file-selector' attribute provides a hash computation of the file to be transferred. This is commonly used by file transfer protocols. For example, FLUTE [FLUTE-REV] uses hashes (called message digests) to verify the contents of the transfer. The purpose of the 'hash' selector is two-fold: On one side, in pull operations, it allows the file receiver to identify a remote file by its hash rather than by its file name, providing that the file receiver has learned the hash of the remote file by some out-of-band mechanism. On the other side, in either push or pull operations, it allows the file receiver to verify the contents of the received file, or even avoid unnecessary transmission of an existing file. The address space of the SHA-1 algorithm is big enough to avoid any collision in hash computations in between two endpoints. When transferring files, the actual file transfer protocol should provide reliable transmission of data, so verifications of received files should always succeed. However, if endpoints need to protect the integrity of a file, they should use some other mechanism than the 'hash' selector specified in this memo. The 'hash' selector includes the hash algorithm and its value. Possible hash algorithms are those defined in the IANA registry of Hash Function Textual Names [IANA]. Implementations according to this specification MUST add a 160-bit string resulting from the computation of US Secure Hash Algorithm 1 (SHA1) [RFC3174] if the 'hash' selector is present. If need arises, extensions can be drafted to support several hashing algorithms. Therefore, implementations according to this specification MUST be prepared to receive SDP containing more than a single 'hash' selector in the 'file-selector' attribute. The value of the 'hash' selector is the byte string resulting from applying the hash algorithm to the content of the whole file, even when the file transfer is limited to a number of octets (i.e., the 'file-range' attribute is indicated). The 'file-transfer-id' attribute provides a randomly chosen globally unique identification to the actual file transfer. It is used to distinguish a new file transfer request from a repetition of the SDP (or the fraction of the SDP that deals with the file description). This attribute is described in much greater detail in Section 8.1.
The 'file-disposition' attribute provides a suggestion to the other endpoint about the intended disposition of the file. Section 7 provides further discussion of the possible values. The value of this attribute SHOULD be the same as the disposition type parameter of the Content-Disposition header field [RFC2183] that would be signaled by the actual file transfer protocol. The 'file-date' attribute indicates the dates on which the file was created, modified, or last read. This attribute MAY contain a combination of the 'creation', 'modification', and 'read' parameters, but MUST NOT contain more than one of each type . The 'creation' parameter indicates the date on which the file was created. The value MUST be a quoted string that contains a representation of the creation date of the file in RFC 5322 [RFC5322] 'date-time' format. Numeric timezones (+HHMM or -HHMM) MUST be used. The value of this parameter SHOULD be the same as the 'creation-date' parameter of the Content-Disposition header field [RFC2183] that would be signaled by the actual file transfer protocol. The 'modification' parameter indicates the date on which the file was last modified. The value MUST be a quoted string that contains a representation of the last modification date to the file in RFC 5322 [RFC5322] 'date-time' format. Numeric timezones (+HHMM or -HHMM) MUST be used. The value of this parameter SHOULD be the same as the 'modification-date' parameter of the Content-Disposition header field [RFC2183] that would be signaled by the actual file transfer protocol. The 'read' parameter indicates the date on which the file was last read. The value MUST be a quoted string that contains a representation of the last date the file was read in RFC 5322 [RFC5322] 'date-time' format. Numeric timezones (+HHMM or -HHMM) MUST be used. The value of this parameter SHOULD be the same as the 'read-date' parameter of the Content-Disposition header field [RFC2183] that would be signaled by the actual file transfer protocol. The 'file-icon' attribute can be useful with certain file types such as images. It allows the file sender to include a pointer to a body that includes a small preview icon representing the contents of the file to be transferred, which the file receiver can use to determine whether it wants to receive such file. The 'file-icon' attribute contains a Content-ID URL, which is specified in RFC 2392 [RFC2392]. Section 8.8 contains further considerations about the 'file-icon' attribute.
The 'file-range' attribute provides a mechanism to signal a chunk of a file rather than the complete file. This enables use cases where a file transfer can be interrupted and resumed, even perhaps changing one of the endpoints. The 'file-range' attribute contains the "start offset" and "stop offset" of the file, separated by a dash "-". The "start offset" value refers to the octet position of the file where the file transfer should start. The first octet of a file is denoted by the ordinal number "1". The "stop offset" value refers to the octet position of the file where the file transfer should stop, inclusive of this octet. The "stop offset" value MAY contain a "*" if the total size of the file is not known in advance. The absence of this attribute indicates a complete file, i.e., as if the 'file- range' attribute would have been present with a value "1-*". The 'file-range' attribute must not be confused with the Byte-Range header in MSRP. The former indicates the portion of a file that the application would read and pass onto the MSRP stack for transportation. From the point of view of MSRP, the portion of the file is viewed as a whole message. The latter indicates the number of bytes of that message that are carried in a chunk and the total size of the message. Therefore, MSRP starts counting the delivered message at octet number 1, independently of the position of that octet in the file. The following is an example of an SDP body that contains the extensions defined in this memo: v=0 o=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com s= c=IN IP4 host.atlanta.example.com t=0 0 m=message 7654 TCP/MSRP * i=This is my latest picture a=sendonly a=accept-types:message/cpim a=accept-wrapped-types:* a=path:msrp://atlanta.example.com:7654/jshA7we;tcp a=file-selector:name:"My cool picture.jpg" type:image/jpeg size:32349 hash:sha-1: 72:24:5F:E8:65:3D:DA:F3:71:36:2F:86:D4:71:91:3E:E4:A2:CE:2E a=file-transfer-id:vBnG916bdberum2fFEABR1FR3ExZMUrd a=file-disposition:attachment a=file-date:creation:"Mon, 15 May 2006 15:01:31 +0300" a=file-icon:cid:id2@alicepc.example.com a=file-range:1-32349 Figure 2: Example of SDP describing a file transfer
NOTE: The 'file-selector' attribute in the above figure is split
in three lines for formatting purposes. Real implementations will
encode it in a single line.
7. File Disposition Types
The SDP offer/answer for file transfer allows the file sender to
indicate a preferred disposition of the file to be transferred in a
new 'file-disposition' attribute. In principle, any value listed in
the IANA registry for Mail Content Disposition Values [IANA] is
acceptable; however, most of them may not be applicable.
There are two content dispositions of interest for file transfer
operations. On one hand, the file sender may just want the file to
be rendered immediately in the file receiver's device. On the other
hand, the file sender may just want to indicate to the file receiver
that the file should not be rendered at the reception of the file.
The recipient's user agent may want to interact with the user
regarding the file disposition or it may save the file until the user
takes an action. In any case, the exact actions are implementation
dependent.
To indicate that a file should be automatically rendered, this memo
uses the existing 'render' value of the Content Disposition type in
the new 'file-disposition' attribute in SDP. To indicate that a file
should not be automatically rendered, this memo uses the existing
'attachment' value of the Content-Disposition type in the new 'file-
disposition' attribute in SDP. The default value is 'render', i.e.,
the absence of a 'file-disposition' attribute in the SDP has the same
semantics as 'render'.
The disposition value 'attachment' is specified in RFC 2183
[RFC2183] with the following definition:
"Body parts can be designated 'attachment' to indicate that
they are separate from the main body of the mail message, and
that their display should not be automatic, but contingent upon
some further action of the user."
In the case of this specification, the 'attachment' disposition
type is used to indicate that the display of the file should not
be automatic, but contingent upon some further action of the user.
(page 13 continued on part 2)
