idnits 2.17.1 draft-ietf-mmusic-file-transfer-mech-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? -- It seems you're using the 'non-IETF stream' Licence Notice instead Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 17, 2009) is 5537 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 3174 ** Obsolete normative reference: RFC 3851 (Obsoleted by RFC 5751) ** Obsolete normative reference: RFC 4566 (Obsoleted by RFC 8866) == Outdated reference: A later version (-16) exists of draft-ietf-rmt-flute-revised-06 Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 MMUSIC Working Group M. Garcia-Martin 3 Internet-Draft Ericsson 4 Intended status: Standards Track M. Isomaki 5 Expires: August 21, 2009 Nokia 6 G. Camarillo 7 S. Loreto 8 Ericsson 9 P. Kyzivat 10 Cisco Systems 11 February 17, 2009 13 A Session Description Protocol (SDP) Offer/Answer Mechanism to Enable 14 File Transfer 15 draft-ietf-mmusic-file-transfer-mech-11.txt 17 Status of this Memo 19 This Internet-Draft is submitted to IETF in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on August 21, 2009. 40 Copyright Notice 42 Copyright (c) 2009 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. 52 Abstract 54 This document provides a mechanism to negotiate the transfer of one 55 or more files between two endpoints by using the Session Description 56 Protocol (SDP) offer/answer model specified in RFC 3264. SDP is 57 extended to describe the attributes of the files to be transferred. 58 The offerer can either describe the files it wants to send, or the 59 files it would like to receive. The answerer can either accept or 60 reject the offer separately for each individual file. The transfer 61 of one or more files is initiated after a successful negotiation. 62 The Message Session Relay Protocol (MSRP) is defined as the default 63 mechanism to actually carry the files between the endpoints. The 64 conventions on how to use MSRP for file transfer are also provided in 65 this document. 67 Table of Contents 69 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 70 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 4. Overview of Operation . . . . . . . . . . . . . . . . . . . . 5 73 5. File selector . . . . . . . . . . . . . . . . . . . . . . . . 7 74 6. Extensions to SDP . . . . . . . . . . . . . . . . . . . . . . 8 75 7. File Disposition Types . . . . . . . . . . . . . . . . . . . . 13 76 8. Protocol Operation . . . . . . . . . . . . . . . . . . . . . . 14 77 8.1. The 'file-transfer-id' attribute . . . . . . . . . . . . . 15 78 8.2. Offerer's Behavior . . . . . . . . . . . . . . . . . . . . 17 79 8.2.1. The Offerer is a File Sender . . . . . . . . . . . . . 18 80 8.2.2. The Offerer is a File Receiver . . . . . . . . . . . . 18 81 8.2.3. SDP Offer for Several Files . . . . . . . . . . . . . 19 82 8.3. Answerer's Behavior . . . . . . . . . . . . . . . . . . . 19 83 8.3.1. The Answerer is a File Receiver . . . . . . . . . . . 20 84 8.3.2. The Answerer is a File Sender . . . . . . . . . . . . 21 85 8.4. Aborting an ongoing file transfer operation . . . . . . . 22 86 8.5. Indicating File Transfer Offer/Answer Capability . . . . . 26 87 8.6. Re-usage of Existing "m=" Lines in SDP . . . . . . . . . . 26 88 8.7. MSRP Usage . . . . . . . . . . . . . . . . . . . . . . . . 26 89 8.8. Considerations about the 'file-icon' attribute . . . . . . 28 90 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 91 9.1. Offerer sends a file to the Answerer . . . . . . . . . . . 29 92 9.2. Offerer requests a file from the Answerer and second 93 file transfer . . . . . . . . . . . . . . . . . . . . . . 33 94 9.3. Example of a capability indication . . . . . . . . . . . . 40 95 10. Security Considerations . . . . . . . . . . . . . . . . . . . 41 96 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 97 11.1. Registration of new SDP attributes . . . . . . . . . . . . 42 98 11.1.1. Registration of the file-selector attribute . . . . . 43 99 11.1.2. Registration of the file-transfer-id attribute . . . . 43 100 11.1.3. Registration of the file-disposition attribute . . . . 43 101 11.1.4. Registration of the file-date attribute . . . . . . . 43 102 11.1.5. Registration of the file-icon attribute . . . . . . . 44 103 11.1.6. Registration of the file-range attribute . . . . . . . 44 104 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 44 105 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 45 106 13.1. Normative References . . . . . . . . . . . . . . . . . . . 45 107 13.2. Informational References . . . . . . . . . . . . . . . . . 46 108 Appendix A. Alternatives Considered . . . . . . . . . . . . . . . 46 109 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 48 111 1. Introduction 113 The Session Description Protocol (SDP) Offer/Answer [RFC3264] 114 provides a mechanism for two endpoints to arrive at a common view of 115 a multimedia session between them. These sessions often contain 116 real-time media streams such as voice and video, but are not limited 117 to that. Basically, any media component type can be supported, as 118 long as there is a specification how to negotiate it within the SDP 119 offer/answer exchange. 121 The Message Session Relay Protocol (MSRP) [RFC4975] is a protocol for 122 transmitting instant messages (IM) in the context of a session. The 123 protocol specification describes the usage of SDP for establishing a 124 MSRP sessions. In addition to plain text messages, MSRP is able to 125 carry arbitrary (binary) Multipurpose Internet Mail Extensions (MIME) 126 [RFC2045] compliant content, such as images or video clips. 128 There are many cases where the endpoints involved in a multimedia 129 session would like to exchange files within the context of that 130 session. With MSRP it is possible to embed files as MIME objects 131 inside the stream of instant messages. MSRP also has other features 132 that are useful for file transfer. Message chunking enables the 133 sharing of the same transport connection between the transfer of a 134 large file and interactive IM exchange without blocking the IM. MSRP 135 relays [RFC4976] provide a mechanism for Network Address Translator 136 (NAT) traversal. Finally, Secure MIME (S/MIME) [RFC3851] can be used 137 for ensuring the integrity and confidentiality of the transferred 138 content. 140 However, the baseline MSRP does not readily meet all the requirements 141 for file transfer services within multimedia sessions. There are 142 four main missing features: 144 o The recipient must be able to distinguish "file transfer" from 145 "file attached to IM", allowing the recipient to treat the cases 146 differently. 147 o It must be possible for the sender to send the request for a file 148 transfer. It must be possible for the recipient to accept or 149 decline it, using the meta information in the request. The actual 150 transfer must take place only after acceptance by the recipient. 151 o It must be possible for the sender to pass some meta information 152 on the file before the actual transfer. This must be able to 153 include at least content type, size, hash and name of the file, as 154 well as a short (human readable) description. 155 o It must be possible for the recipient to request a file from the 156 sender, providing meta information about the file. The sender 157 must be able to decide whether to send a file matching the 158 request. 160 The rest of this document is organized as follows. Section 3 defines 161 a few terms used in this document. Section 4 provides the overview 162 of operation. Section 5 introduces the concept of the file selector. 163 The detailed syntax and semantics of the new SDP attributes and 164 conventions on how the existing ones are used is defined in 165 Section 6. Section 7 discusses the file disposition types. 166 Section 8 describes the protocol operation involving SDP and MSRP. 167 Finally, some examples are given in Section 9. 169 2. Terminology 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 173 document are to be interpreted as described in BCP 14, RFC 2119 174 [RFC2119]. 176 3. Definitions 178 For the purpose of this document, the following definitions specified 179 in RFC 3264 [RFC3264] apply: 181 o Answer 182 o Answerer 183 o Offer 184 o Offerer 186 Additionally, we define the following terms: 188 File sender: The endpoint that is willing to send a file to the 189 file receiver. 190 File receiver: The endpoint that is willing to receive a file from 191 the file sender. 192 File selector: A tuple of file attributes that the SDP offerer 193 includes in the SDP in order to select a file at the SDP answerer. 194 This is described in more detail in Section 5. 195 Push operation: A file transfer operation where the SDP offerer 196 takes the role of the file sender and the SDP answerer takes role 197 of the file receiver. 198 Pull operation: A file transfer operation where the SDP offerer 199 takes the role of the file receiver and the SDP answerer takes the 200 role of the file sender. 202 4. Overview of Operation 204 An SDP offerer creates an SDP body that contains the description of 205 one or more files that the offerer wants to send or receive. The 206 offerer sends the SDP offer to the remote endpoint. The SDP answerer 207 can accept or reject the transfer of each of those files separately. 209 The actual file transfer is carried out using the Message Session 210 Relay Protocol (MSRP) [RFC4975]. Each SDP "m=" line describes an 211 MSRP media stream used to transfer a single file at a time. That is, 212 the transfer of multiple simultaneous files requires multiple "m=" 213 lines and corresponding MSRP media streams. It should be noted that 214 multiple MSRP media streams can share a single transport layer 215 connection, so this mechanism will not lead to excessive use of 216 transport resources. 218 Each "m=" line for an MSRP media stream is accompanied with a few 219 attributes describing the file to be transferred. If the file sender 220 generates the SDP offer, the attributes describe a local file to be 221 sent (push), and the file receiver can use this information to either 222 accept or reject the transfer. However, if the SDP offer is 223 generated by the file receiver, the attributes are intended to 224 characterize a particular file that the file receiver is willing to 225 get (pull) from the file sender. It is possible that the file sender 226 does not have a matching file or does not want to send the file, in 227 which case the offer is rejected. 229 The attributes describing each file are provided in SDP by a set of 230 new SDP attributes, most of which have been directly borrowed from 231 MIME. This way, user agents can decide whether or not to accept a 232 given file transfer based on the file's name, size, description, 233 hash, icon (e.g., if the file is a picture), etc. 235 SDP direction attributes (e.g., 'sendonly', 'recvonly') are used to 236 indicate the direction of the transfer, i.e., whether the SDP offerer 237 is willing to send of receive the file. Assuming that the answerer 238 accepts the file transfer, the actual transfer of the files takes 239 place with ordinary MSRP. Note that the 'sendonly' and 'recvonly' 240 attributes refer to the direction of MSRP SEND requests and do not 241 preclude other protocol elements (such as 200 responses, REPORT 242 requests, etc.). 244 In principle the file transfer can work even with an endpoint 245 supporting only regular MSRP without understanding the extensions 246 defined herein, in a particular case where that endpoint is both 247 the SDP answerer and the file receiver. The regular MSRP endpoint 248 answers the offer as it would answer any ordinary MSRP offer 249 without paying attention to the extension attributes. In such a 250 scenario the user experience would, however, be reduced, since the 251 recipient would not know (by any protocol means) the reason for 252 the session and would not be able to accept/reject it based on the 253 file attributes. 255 5. File selector 257 When the file receiver generates the SDP offer, this SDP offer needs 258 to unambiguously identify the requested file at the file sender. For 259 this purpose we introduce the notion of a file selector, which is a 260 tuple composed of one or more of the following individual selectors: 261 the name, size, type, and hash of the file. The file selector can 262 include any number of selectors, so all four of them do not always 263 need to be present. 265 The purpose of the file selector is to provide enough information 266 about the file to the remote entity, so that both the local and the 267 remote entity can refer to the same file. The file selector is 268 encoded in a 'file-selector' media attribute in SDP. The formal 269 syntax of the 'file-selector' media attribute is described in 270 Figure 1. 272 The file selection process is applied to all the available files at 273 the host. The process selects those file that match each of the 274 selectors present in the 'file-selector' attribute. The result can 275 be zero, one, or more files, depending on the presence of the 276 mentioned selectors in the SDP and depending on the available files 277 in a host. The file transfer mechanism specified in this document 278 requires that a file selector eventually results at most in a single 279 file to be chosen. Typically, if the hash selector is known, it is 280 enough to produce a file selector that points to exactly zero or one 281 file. However, a file selector that selects a unique file is not 282 always known by the offerer. Sometimes only the name, size or type 283 of file are known, so the file selector may result in selecting more 284 than one file, which is an undesired case. The opposite is also 285 true: if the file selector contains a hash selector and a name 286 selector, there is a risk that the remote host has renamed the file, 287 in which case, although a file whose computed hash equals the hash 288 selector exists, the file name does not match that of the name 289 selector, thus, the file selection process will result in the 290 selection of zero files. 292 This specification uses the Secure Hash Algorithm 1, SHA-1 [RFC3174]. 293 If future needs require adding support for different hashing 294 algorithms, they will be specified as extensions to this document. 296 Implementations according to this specification MUST implement the 297 'file-selector' attribute and MAY implement any of the other 298 attributes specified in this specification. SDP offers and answers 299 for file transfer MUST contain a 'file-selector' media attribute that 300 selects the file to be transferred and MAY contain any of the other 301 attributes specified in this specification. 303 The 'file-selector' media attribute is also useful when learning the 304 support of the file transfer offer/answer capability that this 305 document specifies. This is further explained in Section 8.5. 307 6. Extensions to SDP 309 We define a number of new SDP [RFC4566] attributes that provide the 310 required information to describe the transfer of a file with MSRP. 311 These are all media level only attributes in SDP. The following is 312 the formal ABNF syntax [RFC5234] of these new attributes. It is 313 built above the SDP [RFC4566] grammar, RFC 2045 [RFC2045], RFC 2183 314 [RFC2183], RFC 2392 [RFC2392], and RFC 5322 [RFC5322]. 316 attribute /= file-selector-attr / file-disp-attr / 317 file-tr-id-attr / file-date-attr / 318 file-icon-attr / file-range-attr 319 ;attribute is defined in RFC 4566 321 file-selector-attr = "file-selector" [":" selector *(SP selector)] 322 selector = filename-selector / filesize-selector / 323 filetype-selector / hash-selector 325 filename-selector = "name:" DQUOTE filename-string DQUOTE 326 ; DQUOTE defined in RFC 5234 327 filename-string = 1*(filename-char/percent-encoded) 328 filename-char = %x01-09/%x0B-0C/%x0E-21/%x23-24/%x26-FF 329 ;any byte except NUL, CR, LF, 330 ;double quotes, or percent 331 percent-encoded = "%" HEXDIG HEXDIG 332 ; HEXDIG defined in RFC 5234 334 filesize-selector = "size:" filesize-value 335 filesize-value = integer ;integer defined in RFC 4566 337 filetype-selector = "type:" type "/" subtype *(";" ft-parameter) 339 ft-parameter = attribute "=" DQUOTE value-string DQUOTE 340 ; attribute is defined in RFC 2045 341 ; free insertion of linear-white-space is not 342 ; permitted in this context. 343 ; note: value-string has to be re-encoded 344 ; when translating between this and a 345 ; Content-Type header. 346 value-string = filename-string 347 hash-selector = "hash:" hash-algorithm ":" hash-value 348 hash-algorithm = token ;see IANA Hash Function 349 ;Textual Names registry 350 ;only "sha-1" currently supported 351 hash-value = 2HEXDIG *(":" 2HEXDIG) 352 ; Each byte in upper-case hex, separated 353 ; by colons. 354 ; HEXDIG defined in RFC 5234 356 file-tr-id-attr = "file-transfer-id:" file-tr-id-value 357 file-tr-id-value = token 359 file-disp-attr = "file-disposition:" file-disp-value 360 file-disp-value = token 362 file-date-attr = "file-date:" date-param *(SP date-param) 364 date-param = c-date-param / m-date-param / r-date-param 365 c-date-param = "creation:" DQUOTE date-time DQUOTE 366 m-date-param = "modification:" DQUOTE date-time DQUOTE 367 r-date-param = "read:" DQUOTE date-time DQUOTE 368 ; date-time is defined in RFC 5322 369 ; numeric timezones (+HHMM or -HHMM) 370 ; must be used 371 ; DQUOTE defined in RFC 5234 files. 373 file-icon-attr = "file-icon:" file-icon-value 374 file-icon-value = cid-url ;cid-url defined in RFC 2392 376 file-range-attr = "file-range:" start-offset "-" stop-offset 377 start-offset = integer ;integer defined in RFC 4566 378 stop-offset = integer / "*" 380 Figure 1: Syntax of the SDP extension 382 When used for capability query (see Section 8.5), the 'file-selector' 383 attribute MUST NOT contain any selector, because its presence merely 384 indicates compliance to this specification. 386 When used in an SDP offer or answer, the 'file-selector' attribute 387 MUST contain at least one selector. Selectors characterize the file 388 to be transferred. There are four selectors in this attribute: 389 'name', 'size', 'type', and 'hash'. 391 The 'name' selector in the 'file-selector' attribute contains the 392 filename of the content enclosed in double quotes. The filename is 393 encoded in UTF-8 [RFC3629]. Its value SHOULD be the same as the 394 'filename' parameter of the Content-Disposition header field 396 [RFC2183] that would be signaled by the actual file transfer. If a 397 file name contains double quotes or any other character that the 398 syntax does not allow in the 'name' selector, they MUST be percent- 399 encoded. The 'name' selector MUST NOT contain characters that can be 400 interpreted as directory structure by the local operating system. If 401 such characters are present in the file name, they MUST be percent- 402 encoded. 404 Note that the 'name' selector might still contain characters that, 405 although not meaningful for the local operating system, might 406 still be meaningful to the remote operating system (e.g., '\', 407 '/', ':'). Therefore, implementations are responsible for 408 sanitizing the input received from the remote endpoint before 409 doing a local operation in the local file system, such as the 410 creation of a local file. Among other things, implementations can 411 percent-encode characters that are meaningful to the local 412 operating system before doing file system local calls. 414 The 'size' selector in the 'file-selector' attribute indicates the 415 size of the file in octets. The value of this attribute SHOULD be 416 the same as the 'size' parameter of the Content-Disposition header 417 field [RFC2183] that would be signaled by the actual file transfer. 418 Note that the 'size' selector merely includes the file size, and does 419 not include any potential overhead added by a wrapper, such as 420 message/cpim [RFC3862]. 422 The 'type' selector in the 'file-selector' attribute contains the 423 MIME media and submedia types of the content. In general, anything 424 that can be expressed in a Content-Type header field (see RFC 2045 425 [RFC2045]) can also be expressed with the 'type' selectors. Possible 426 MIME Media Type values are the ones listed in the IANA registry for 427 MIME Media Types [1]. Zero or more parameters can follow. When 428 translating parameters from a Content-Type header and a 'type' 429 selector, the parameter has to be re-encoded prior to its 430 accommodation as a parameter of the 'type' selector (see the ABNF 431 syntax of 'ft-parameter'). 433 The 'hash' selector in the 'file-selector' attribute provides a hash 434 computation of the file to be transferred. This is commonly used by 435 file transfer protocols. For example, FLUTE 436 [I-D.ietf-rmt-flute-revised] uses hashes (called message digests) to 437 verify the contents of the transfer. The purpose of the 'hash' 438 selector is two-fold: On one side, in pull operations, it allows the 439 file receiver to identify a remote file by its hash rather than by 440 its file name, providing that the file receiver has learned the hash 441 of the remote file by some out-of-band mechanism. On the other side, 442 in either push or pull operations, it allows the file receiver to 443 verify the contents of the received file, or even avoid unnecessary 444 transmission of an existing file. 446 The address space of the SHA-1 algorithm is big enough to avoid 447 any collision in hash computations in between two endpoints. When 448 transferring files, the actual file transfer protocol should 449 provide reliable transmission of data, so verifications of 450 received files should always succeed. However, if endpoints need 451 to protect the integrity of a file, they should use some other 452 mechanism than the 'hash' selector specified in this memo. 454 The 'hash' selector includes the hash algorithm and its value. 455 Possible hash algorithms are those defined in the IANA registry of 456 Hash Function Textual Names [2]. Implementations according to this 457 specification MUST add a 160-bit string resulting from the 458 computation of US Secure Hash Algorithm 1 (SHA1) [RFC3174] if the 459 'hash' selector is present. If need arises, extensions can be 460 drafted to support several hashing algorithms. Therefore, 461 implementations according to this specification MUST be prepared to 462 receive SDP containing more than a single 'hash' selector in the 463 'file-selector' attribute. 465 The value of the 'hash' selector is the byte string resulting of 466 applying the hash algorithm to the content of the whole file, even 467 when the file transfer is limited to a number of octets (i.e., the 468 'file-range' attribute is indicated). 470 The 'file-transfer-id' attribute provides a randomly chosen globally 471 unique identification to the actual file transfer. It is used to 472 distinguish a new file transfer request from a repetition of the SDP 473 (or the fraction of the SDP that deals with the file description). 474 This attribute is described in much greater detail in Section 8.1. 476 The 'file-disposition' attribute provides a suggestion to the other 477 endpoint about the intended disposition of the file. Section 7 478 provides further discussion of the possible values. The value of 479 this attribute SHOULD be the same as the disposition type parameter 480 of the Content-Disposition header field [RFC2183] that would be 481 signaled by the actual file transfer protocol. 483 The 'file-date' attribute indicates the dates at which the file was 484 created, modified, or last read. This attribute MAY contain a 485 combination of the 'creation', 'modification', and 'read' parameters, 486 but MUST NOT contain more than one of each type . 488 The 'creation' parameter indicates the date at which the file was 489 created. The value MUST be a quoted string which contains a 490 representation of the creation date of the file in RFC 5322 [RFC5322] 491 'date-time' format. Numeric timezones (+HHMM or -HHMM) MUST be used. 493 The value of this parameter SHOULD be the same as the 'creation-date' 494 parameter of the Content-Disposition header field [RFC2183] that 495 would be signaled by the actual file transfer protocol. 497 The 'modification' parameter indicates the date at which the file was 498 last modified. The value MUST be a quoted string which contains a 499 representation of the last modification date to the file in RFC 5322 500 [RFC5322] 'date-time' format. Numeric timezones (+HHMM or -HHMM) 501 MUST be used. The value of this parameter SHOULD be the same as the 502 'modification-date' parameter of the Content-Disposition header field 503 [RFC2183] that would be signaled by the actual file transfer 504 protocol. 506 The 'read' parameter indicates the date at which the file was last 507 read. The value MUST be a quoted string which contains a 508 representation of the last date the file was read in RFC 5322 509 [RFC5322] 'date-time' format. Numeric timezones (+HHMM or -HHMM) 510 MUST be used. The value of this parameter SHOULD be the same as the 511 'read-date' parameter of the Content-Disposition header field 512 [RFC2183] that would be signaled by the actual file transfer 513 protocol. 515 The 'file-icon' attribute can be useful with certain file types such 516 as images. It allows the file sender to include a pointer to a body 517 that includes a small preview icon representing the contents of the 518 file to be transferred, which the file receiver can use to determine 519 whether it wants to receive such file. The 'file-icon' attribute 520 contains a Content-ID URL, which is specified in RFC 2392 [RFC2392]. 521 Section 8.8 contains further considerations about the 'file-icon' 522 attribute. 524 The 'file-range' attribute provides a mechanism to signal a chunk of 525 a file rather than the complete file. This enable use cases where a 526 file transfer can be interrupted, resumed, even perhaps changing one 527 of the endpoints. The 'file-range' attribute contains the "start 528 offset" and "stop offset" of the file, separated by a dash "-". The 529 "start offset" value refers to the octet position of the file where 530 the file transfer should start. The first octet of a file is denoted 531 by the ordinal number "1". The "stop offset" value refers to the 532 octet position of the file where the file transfer should stop, 533 inclusive of this octet. The "stop offset" value MAY contain a "*" 534 if the total size of the file is not known in advance. The absence 535 of this attribute indicates a complete file, i.e., as if the 'file- 536 range' attribute would have been present with a value "1-*". The 537 'file-range' attribute must not be confused with the Byte-Range 538 header in MSRP. The former indicates the portion of a file that the 539 application would read and pass onto the MSRP stack for 540 transportation. From the point of view of MSRP, the portion of the 541 file is viewed as a whole message. The latter indicates the number 542 of bytes of that message that are carried in a chunk and the total 543 size of the message. Therefore, MSRP starts counting the delivered 544 message at octet number 1, independently of position of that octet in 545 the file. 547 The following is an example of an SDP body that contains the 548 extensions defined in this memo: 550 v=0 551 o=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com 552 s= 553 c=IN IP4 host.atlanta.example.com 554 t=0 0 555 m=message 7654 TCP/MSRP * 556 i=This is my latest picture 557 a=sendonly 558 a=accept-types:message/cpim 559 a=accept-wrapped-types:* 560 a=path:msrp://atlanta.example.com:7654/jshA7we;tcp 561 a=file-selector:name:"My cool picture.jpg" type:image/jpeg 562 size:32349 hash:sha-1: 563 72:24:5F:E8:65:3D:DA:F3:71:36:2F:86:D4:71:91:3E:E4:A2:CE:2E 564 a=file-transfer-id:vBnG916bdberum2fFEABR1FR3ExZMUrd 565 a=file-disposition:attachment 566 a=file-date:creation:"Mon, 15 May 2006 15:01:31 +0300" 567 a=file-icon:cid:id2@alicepc.example.com 568 a=file-range:1-32349 570 Figure 2: Example of SDP describing a file transfer 572 NOTE: The 'file-selector' attribute in the above figure is split 573 in three lines for formatting purposes. Real implementations will 574 encode it in a single line. 576 7. File Disposition Types 578 The SDP Offer/Answer for file transfer allows the file sender to 579 indicate a preferred disposition of the file to be transferred in a 580 new 'file-disposition' attribute. In principle, any value listed in 581 the IANA registry for Mail Content Disposition Values [3] is 582 acceptable, however, most of them may not be applicable. 584 There are two content dispositions of interest for file transfer 585 operations. On one hand, the file sender may just want the file to 586 be rendered immediately in the file receiver's device. On the other 587 hand, the file sender may just want to indicate to the file receiver 588 that the file should not be rendered at the reception of the file. 589 The recipient's user agent may want to interact with the user 590 regarding the file disposition or it may save the file until the user 591 takes an action. In any case, the exact actions are implementation 592 dependent. 594 To indicate that a file should be automatically rendered, this memo 595 uses the existing 'render' value of the Content Disposition type in 596 the new 'file-disposition' attribute in SDP. To indicate that a file 597 should not be automatically rendered, this memo users the existing 598 'attachment' value of the Content-Disposition type in the new 'file- 599 disposition' attribute in SDP. The default value is 'render', i.e., 600 the absence of a 'file-disposition' attribute in the SDP has the same 601 semantics as 'render'. 603 The disposition value 'attachment' is specified in RFC 2183 604 [RFC2183] with the following definition: 606 "Body parts can be designated 'attachment' to indicate that 607 they are separate from the main body of the mail message, and 608 that their display should not be automatic, but contingent upon 609 some further action of the user." 610 In the case of this specification, the 'attachment' disposition 611 type is used to indicate that the display of the file should not 612 be automatic, but contingent upon some further action of the user. 614 8. Protocol Operation 616 This section discusses how to use the parameters defined in Section 6 617 in the context of an offer/answer [RFC3264] exchange. Additionally, 618 this section also discusses the behavior of the endpoints using MSRP. 620 A file transfer session is initiated by the offerer sending an SDP 621 offer to the answerer. The answerer either accepts or rejects the 622 file transfer session and sends an SDP answer to the offerer. 624 We can differentiate two use cases, depending on whether the offerer 625 is the file sender or file receiver: 627 1. The offerer is the file sender, i.e., the offerer wants to 628 transmit a file to the answerer. Consequently the answerer is 629 the file receiver. In this case the SDP offer contains a 630 'sendonly' attribute, and accordingly the SDP answer contains a 631 'recvonly' attribute. 632 2. The offerer is the file receiver, i.e., the offerer wants to 633 fetch a file from the answerer. Consequently the answerer is the 634 file sender. In this case the SDP offer contains a session or 635 media 'recvonly' attribute, and accordingly the SDP answer 636 contains a session or media 'sendonly' attribute. 638 8.1. The 'file-transfer-id' attribute 640 This specification creates an extension to the SDP Offer/Answer Model 641 [RFC3264], and because of that, it is assumed that the existing SDP 642 behavior is kept intact. The SDP behavior requires, for example, 643 that SDP is sent again to the remote party in situations where the 644 media description or perhaps other SDP parameters have not changed 645 with respect a previous offer/answer exchange. Let's consider the 646 SIP Session Timer (RFC 4028) [RFC4028], which uses re-INVITE requests 647 to refresh sessions. RFC 4028 recommends to send unmodified SDP in a 648 re-INVITE to refresh the session. Should this re-INVITE contain SDP 649 describing a file transfer operation and occur while the file 650 transfer was still going on, there would be no means to detect 651 whether the SDP creator wanted to abort the current file transfer 652 operation and initiate a new one or the SDP file description was 653 included in the SDP due to other reasons (e.g., session timer 654 refresh). 656 A similar scenario occurs when two endpoints have successfully agreed 657 on a file transfer, which is currently taking place when one of the 658 endpoints wants to add additional media streams to the existing 659 session. In this case, the endpoint sends a re-INVITE request that 660 contains SDP. The SDP needs to maintain the media descriptions for 661 the current ongoing file transfer and add the new media descriptions. 662 The problem is that, the other endpoint is not able to determine if a 663 new file transfer is requested or not. 665 In other cases, a file transfer was successfully completed. Then, if 666 an endpoint re-sends the SDP offer with the media stream for the file 667 transfer, then the other endpoint wouldn't be able to determine 668 whether a new file transfer should start or not. 670 To address these scenarios this specification defines the 'file- 671 transfer-id' attribute which contains a globally unique random 672 identifier allocated to the file transfer operation. The file 673 transfer identifier helps both endpoints to determine whether the SDP 674 offer is requesting a new file transfer or it is a repetition of the 675 SDP. A new file transfer is one that, in case of acceptance, will 676 provoke the actual transfer of a file. This is typically the case of 677 new offer/answer exchanges, or in cases where an endpoint wants to 678 abort the existing file transfer and re-start the file transfer once 679 more. On the other hand, the repetition of the SDP does not lead to 680 any actual file to be transferred, potentially because the file 681 transfer is still going on or because it has already finished. This 682 is the case of repeated offer/answer exchanges, which can be due to a 683 number of reasons (session timer, addition/removal of other media 684 types in the SDP, update in SDP due to changes in other session 685 parameters, etc.). 687 Implementations according to this specification MUST include a 'file- 688 transfer-id' attribute in SDP offers and answers. The SDP offerer 689 MUST select a file transfer identifier according to the syntax and 690 add it to the 'file-transfer-id' attribute. The SDP answerer MUST 691 copy the value of the 'file-transfer-id' attribute in the SDP answer. 693 The file transfer identifier MUST be unique within the current 694 session (never used before in this session), and it is RECOMMENDED to 695 be unique across different sessions. It is RECOMMENDED to select a 696 relatively big random identifier (e.g., 32 characters) to avoid 697 duplications. The SDP answerer MUST keep track of the proposed file 698 transfer identifiers in each session and copy the value of the 699 received file transfer identifier in the SDP answer. 701 If a file transfer is suspended and resumed at a later time, the 702 resumption is considered a new file transfer (even when the file to 703 be transferred is the same), therefore, the SDP offerer MUST choose a 704 new file transfer identifier. 706 If an endpoint sets the port number to zero in the media description 707 of a file transfer, for example because it wants to reject the file 708 transfer operation, then the SDP answer MUST mirror the value of the 709 'file-transfer-id' attribute included in the SDP offer. This 710 effectively means that setting a media stream to zero has higher 711 precedence than any value that the 'file-transfer-id' attribute can 712 take. 714 As a side effect, the 'file-transfer-id' attribute can be used for 715 aborting and restarting again an ongoing file transfer. Assume that 716 two endpoints agree on a file transfer and the actual transfer of the 717 file is taking place. At some point in time in the middle of the 718 file transfer, one endpoint sends a new SDP offer, equal to the 719 initial one except for the value of the 'file-transfer-id' attribute, 720 which is a new globally unique random value. This indicates that the 721 offerer wants to abort the existing transfer and start a new one, 722 according to the SDP parameters. The SDP answerer SHOULD abort the 723 ongoing file transfer, according to the procedures of the file 724 transfer protocol (e.g., MSRP), and start sending file once more from 725 the initial requested octet. Section 8.4 further discusses file 726 transfer abortion. 728 If an endpoint creates an SDP offer where the 'file-transfer-id' 729 attribute value does not change with respect a previously sent one, 730 but the file selector changes so that a new file is selected, then 731 this is considered and error, and the SDP answerer MUST abort the 732 file transfer operation (e.g., by setting the port number to zero in 733 the SDP answer). Note that endpoints MAY change the 'file-selector' 734 attribute as long as the selected file does not change (e.g., by 735 adding a hash selector), however it is RECOMMENDED that endpoints do 736 not change the value of the 'file-selector' attribute if it is 737 requested to transfer the same file described in a previous SDP 738 offer/answer exchange. 740 Figure 3 summarizes the relation of the 'file-transfer-id' attribute 741 with the file selector in subsequent SDP exchanges. 743 \ | | | 744 \ file selector | different | same | 745 'file-transfer-id' \ | file | file | 746 ==================================+=============+===============+ 747 | new file | new file | 748 changed | transfer | transfer | 749 | operation | operation | 750 ----------------------------------+-------------+---------------+ 751 | | existing file | 752 unchanged | error | transfer | 753 | | operation | 754 ----------------------------------+-------------+---------------+ 756 Figure 3: Relation of the 'file-transfer-id' attribute with the 757 selector of the file in a subsequent SDP exchange 759 In another scenario, an endpoint that has successfully transferred a 760 file wants to send an SDP due to other reasons than the transfer of a 761 file. The SDP offerer creates an SDP file description that maintains 762 the media description line corresponding to the file transfer. The 763 SDP offerer MUST then set the port number to zero and MUST keep the 764 same value of the 'file-transfer-id' attribute that the initial file 765 transfer got. 767 8.2. Offerer's Behavior 769 An offerer who wishes to send or receive one or more files to or from 770 an answerer MUST build an SDP [RFC4566] description of a session 771 containing one "m=" line per file. When MSRP is used as the transfer 772 mechanism, each "m=" line also describes a single MSRP session, 773 according to the MSRP [RFC4975] procedures. Any "m=" lines that may 774 have already been present in a previous SDP exchange are normally 775 kept unmodified; the new "m=" lines are added afterwards (Section 8.6 776 describes cases when "m=" lines are re-used). All the media line 777 attributes specified and required by MSRP [RFC4975] (e.g., "a=path", 778 "a=accept-types", etc.) MUST be included as well. 780 8.2.1. The Offerer is a File Sender 782 In a push operation, the file sender creates and SDP offer describing 783 the file to be sent. The file sender MUST add a 'file-selector' 784 attribute media line containing at least one of the 'type', 'size', 785 'hash' selectors in indicating the type, size, or hash of the file, 786 respectively. If the file sender wishes to start a new file 787 transfer, the file sender MUST add a 'file-transfer-id' attribute 788 containing a new globally unique random identifier value. 789 Additionally, the file sender MUST add a session or media 'sendonly' 790 attribute to the SDP offer. Then the file sender sends the SDP offer 791 to the file receiver. 793 Not all the selectors in the 'file-selector' attribute might be 794 known when the file sender creates the SDP offer, for example, 795 because the host is still processing the file. 797 The 'hash' selector in the 'file-selector' attribute contains 798 valuable information to the file receiver to identify whether the 799 file is already available and need not be transmitted. 801 The file sender MAY also add a 'name' selector in the 'file-selector' 802 attribute, and a 'file-icon', 'file-disposition', and 'file-date' 803 attributes further describing the file to be transferred. The 'file- 804 disposition' attribute provides a presentation suggestion, (for 805 example: the file sender would like the file receiver to render the 806 file or not). The three date attributes provide the answerer with an 807 indication of the age of the file. The file sender MAY also add a 808 'file-range' attribute indicating the start and stop offsets of the 809 file. 811 When the file sender receives the SDP answer, if the port number of 812 the answer for a file request is non-zero, the file sender starts the 813 transfer of the file according to the negotiated parameters in SDP. 815 8.2.2. The Offerer is a File Receiver 817 In a pull operation, the file receiver creates the SDP offer and 818 sends it to the file sender. The file receiver MUST include a 'file- 819 selector' attribute and MUST include, at least, one of the selectors 820 defined for such attribute (i.e., 'name', 'type', 'size', or 'hash'). 821 In many cases, if the hash of the file is known, that is enough to 822 identify the file, therefore, the offerer can include only a 'hash' 823 selector. However, specially in cases where the hash of the file is 824 unknown, the file name, size, and type can provide a description of 825 the file to be fetched. If the file receiver wishes to start a new 826 file transfer it MUST add a 'file-transfer-id' attribute containing a 827 new globally unique random value. The file receiver MAY also add a 828 'file-range' attribute indicating the start and stop offsets of the 829 file. There is no need to for the file receiver to include further 830 file attributes in the SDP offer, thus it is RECOMMENDED that SDP 831 offerers do not include any other file attribute defined by this 832 specification (other than the mandatory ones). Additionally, the 833 file receiver MUST add a session or media 'recvonly' attribute in the 834 SDP offer. Then file receiver sends the SDP offer to the file 835 sender. 837 When the file receiver receives the SDP answer, if the port number of 838 the answer for a file request is non-zero, then the file receiver 839 should receive the file using the protocol indicated in the "m=" 840 line. If the SDP answer contains a supported hashing algorithm in 841 the 'hash' selectors of the 'file-selector' attribute, then the file 842 receiver SHOULD compute the hash of the file after its reception and 843 check it against the hash received in the answer. In case the 844 computed hash does not match the one contained in the SDP answer, the 845 file receiver SHOULD consider that the file transfer failed and 846 SHOULD inform the user. Similarly, the file receiver SHOULD also 847 verify that the other selectors declared in the SDP match the file 848 properties, otherwise, the file receiver SHOULD consider that the 849 file transfer failed and SHOULD inform the user. 851 8.2.3. SDP Offer for Several Files 853 An offerer that wishes to send or receive more than one file 854 generates an "m=" line per file along with the file attributes 855 described in this specification. This way, the answerer can reject 856 individual files by setting the port number of their associated "m=" 857 lines to zero, as per regular SDP [RFC4566] procedures. Similarly, 858 the answerer can accept each individual file separately by setting 859 the port number of their associated "m=" lines to non-zero value. 860 Each file has its own file transfer identifier, which uniquely 861 identifies each file transfer. 863 Using an "m=" line per file implies that different files are 864 transferred using different MSRP sessions. However, all those MSRP 865 sessions can be set up to run over a single TCP connection, as 866 described in Section 8.1 of RFC 4975 [RFC4975]. The same TCP 867 connection can also be re-used for sequential file transfers. 869 8.3. Answerer's Behavior 871 If the answerer wishes to reject a file offered by the offerer, it 872 sets the port number of the "m=" line associated with the file to 873 zero, as per regular SDP [RFC4566] procedures. The rejected answer 874 MUST contained a 'file-selector' and 'file-transfer-id' attributes 875 whose values mirror the corresponding values of the SDP offer. 877 If the answerer decides to accept the file, it proceeds as per 878 regular MSRP [RFC4975] and SDP [RFC4566] procedures. 880 8.3.1. The Answerer is a File Receiver 882 In a push operation the SDP answerer is the file receiver. When the 883 file receiver gets the SDP offer, it first examines the port number. 884 If the port number is set to zero, the file transfer operation is 885 closed, and no more data is expected over the media stream. Then, if 886 the port number is different than zero, the file receiver inspects 887 the 'file-transfer-id' attribute. If the value of the 'file- 888 transfer-id' attribute has been previously used then the existing 889 session remains without changes, perhaps the file transfer is still 890 in progress, or perhaps it has concluded, but there are no change 891 with respect the current status. In any case, independently of the 892 port number, the SDP answerer creates a regular SDP answer and sends 893 it to the offerer. 895 If the port number is different than zero and the SDP offer contains 896 a new 'file-transfer-id' attribute, then it is signaling a request 897 for a new file transfer. The SDP answerer extracts the attributes 898 and parameters that describe the file and typically requests 899 permission from the user to accept or reject the reception of the 900 file. If the file transfer operation is accepted, the file receiver 901 MUST create an SDP answer according to the procedures specified in 902 RFC 3264 [RFC3264]. If the offer contains 'name', 'type', 'size' 903 selectors in the 'file-selector' attribute, the answerer MUST copy 904 them into the answer. The file receiver copies the value of the 905 'file-transfer-id' attribute to the SDP answer. Then the file 906 receiver MUST add a session or media 'recvonly' attribute according 907 to the procedures specified in RFC 3264 [RFC3264]. The file receiver 908 MUST NOT include 'file-icon', 'file-disposition', or 'file-date' 909 attributes in the SDP answer. 911 The file receiver can use the hash to find out if a local file with 912 the same hash is already available, in which case, this could imply 913 the reception of a duplicated file. It is up to the answerer to 914 determine whether the file transfer is accepted or not in case of a 915 duplicated file. 917 If the SDP offer contains a 'file-range' attribute and the file 918 receiver accepts to receive the range of octets declared in there, 919 the file receiver MUST include a 'file-range' attribute in the SDP 920 answer with the same range of values. If the file receiver does not 921 accept the reception of that range of octets, it SHOULD reject the 922 transfer of the file. 924 When the file transfer operation is complete, the file receiver 925 computes the hash of the file and SHOULD verify that it matches the 926 hash declared in the SDP. If they do not match, the file receiver 927 SHOULD consider that the file transfer failed and SHOULD inform the 928 user. Similarly, the file receiver SHOULD also verify that the other 929 selectors declared in the SDP match the file properties, otherwise, 930 the file receiver SHOULD consider that the file transfer failed and 931 SHOULD inform the user. 933 8.3.2. The Answerer is a File Sender 935 In a pull operation the answerer is the file sender. In this case, 936 the SDP answerer MUST first inspect the value of the 937 'file-transfer-id' attribute. If it has not been previously been 938 used throughout the session, then acceptance of the file MUST provoke 939 the transfer of the file over the negotiated protocol. However, if 940 the value has been previously used by another file transfer operation 941 within the session, then the file sender MUST NOT alert the user and 942 MUST NOT start a new transfer of the file. No matter whether an 943 actual file transfer is initiated or not, the file sender MUST create 944 a proper SDP answer that contains the 'file-transfer-id' attribute 945 with the same value received in the SDP offer, and then it MUST 946 continue processing the SDP answer. 948 The file sender MUST always create an SDP answer according to the SDP 949 offer/answer procedures specified in RFC 3264 [RFC3264]. The file 950 sender inspects the file selector of the received SDP offer, which is 951 encoded in the 'file-selector' media attribute line. Then the file 952 sender applies the file selector, which implies selecting those files 953 that match one by one with the 'name', 'type', 'size', and 'hash' 954 selectors of the 'file-selector' attribute line (if they are 955 present). The file selector identifies zero or more candidate files 956 to be sent. If the file selector is unable to identify any file, 957 then the answerer MUST reject the MSRP stream for file transfer by 958 setting the port number to zero, and then the answerer SHOULD also 959 reject the SDP as per procedures in RFC 3264 [RFC3264], if this is 960 the only stream described in the SDP offer. 962 If the file selector points to a single file and the file sender 963 decides to accept the file transfer, the file sender MUST create an 964 SDP answer that contains a 'sendonly' attribute, according to the 965 procedures described RFC 3264 [RFC3264]. The file sender SHOULD add 966 a 'hash' selector in the answer with the locally computed SHA-1 hash 967 over the complete file. If a hash value computed by the file sender 968 differs from that specified by the file receiver, the file sender can 969 either send the file without that hash value or reject the request by 970 setting the port in the media stream to zero. The file sender MAY 971 also include a 'type' selector in the 'file-selector' attribute line 972 of the SDP answer. The answerer MAY also include a 'file-icon' and 973 'file-disposition' attributes to further describe the file. Although 974 the answerer MAY also include a 'name' and 'size' selectors in the 975 'file-selector' attribute, and a 'file-date' attribute, it is 976 RECOMMENDED not to include them in the SDP answer if the actual file 977 transfer protocol (e.g., MSRP [RFC4975]) can accommodate a Content- 978 Disposition header field [RFC2183] with the equivalent parameters. 980 The whole idea of adding file descriptors to SDP is to provide a 981 mechanism where a file transfer can be accepted prior to its 982 start. Adding any SDP attributes that are otherwise signaled 983 later in the file transfer protocol would just duplicate the 984 information, but will not provide any information to the offerer 985 to accept or reject the file transfer (note that the offerer is 986 requesting a file). 988 Last, if the file selector points to multiple candidate files, the 989 answerer MAY use some local policy, e.g. consulting the user, to 990 choose one of them to be defined in the SDP answer. If that choice 991 cannot be done, the answerer SHOULD reject the MSRP media stream for 992 file transfer (by setting the port number to zero). 994 If the need arises, future specifications can provide a suitable 995 mechanism that allows to either select multiple files or, e.g., 996 resolve ambiguities by returning a list of files that match the 997 file selector. 999 If the SDP offer contains a 'file-range' attribute and the file 1000 sender accepts to send the range of octets declared in there, the 1001 file sender MUST include a 'file-range' attribute in the SDP answer 1002 with the same range of values. If the file sender does not accept 1003 sending that range of octets, it SHOULD reject the transfer of the 1004 file. 1006 8.4. Aborting an ongoing file transfer operation 1008 Either the file sender or the file receiver can abort an ongoing file 1009 transfer at any time. Unless otherwise noted, the entity that aborts 1010 an ongoing file transfer operation MUST follow the procedures at the 1011 media level (e.g., MSRP) and at the signaling level (SDP Offer/ 1012 answer), as described below. 1014 Assume the scenario depicted in Figure 4 where a file sender wishes 1015 to abort an ongoing file transfer without initiating an alternative 1016 file transfer. Assume that an ongoing MSRP SEND request is being 1017 transmitted. The file sender aborts the MSRP message by including 1018 the '#' character in the continuation field of the end-line of a SEND 1019 request, according to the MSRP procedures (see Section 7.1 of RFC 1020 4975 [RFC4975]). Since a file is transmitted as one MSRP message, 1021 aborting the MSRP message effectively aborts the file transfer. The 1022 file receiver acknowledges the MSRP SEND request with a 200 response. 1023 Then the file sender SHOULD close the MSRP session by creating a new 1024 SDP offer that sets the port number to zero in the related "m=" line 1025 that describes the file transfer (see Section 8.2 of RFC 3264 1026 [RFC3264]). This SDP offer MUST conform with the requirements of 1027 Section 8.2.1. The 'file-transfer-id' attribute MUST be the same 1028 that identifies the ongoing transfer. Then the file sender sends 1029 this SDP offer to the file receiver. 1031 Rather than close the MSRP session by setting the port number to 1032 zero in the related "m=" line, the file sender could also tear 1033 down the whole session, e.g., by sending a SIP BYE request. 1035 Note that it is responsibility of the file sender to tear down the 1036 MSRP session. Implementations should be prepared for misbehaviors 1037 and implement measures to avoid hang states. For example, upon 1038 expiration of a timer the file receiver can close the aborted MSRP 1039 session by using regular MSRP procedures. 1041 A file receiver that receives the above SDP offer creates an SDP 1042 answer according to the procedures of the SDP offer/answer (RFC 3264 1043 [RFC3264]). This SDP answer MUST conform with the requirements of 1044 Section 8.3.1. Then the file receiver sends this SDP answer to the 1045 file sender. 1047 File sender File receiver 1048 | | 1049 |\ | 1050 | \ | 1051 | \ | 1052 | \ | 1053 | \ | 1054 | \ | 1055 abort->| \ MSRP SEND (#) | 1056 | +--------------->| 1057 | MSRP 200 | 1058 |<-----------------------| 1059 | re-INVITE (SDP offer) | 1060 |----------------------->| 1061 | SIP 200 OK (SDP answer)| 1062 |<-----------------------| 1063 | SIP ACK | 1064 |----------------------->| 1065 | | 1067 Figure 4: File sender aborts an ongoing file transfer 1069 When the file receiver wants to abort the file transfer, there are 1070 two possible scenarios, depending on the value of the Failure-Report 1071 header in the ongoing MSRP SEND request. Assume now the scenario 1072 depicted in Figure 5 where the MSRP SEND request includes a Failure- 1073 Report header set to a value different than "no". When the file 1074 receiver wishes to abort the ongoing file transfer, the file receiver 1075 generates an MSRP 413 response to the current MSRP SEND request (see 1076 Section 10.5 of RFC 4975 [RFC4975]). Then the file receiver MUST 1077 close the MSRP session by generating a new SDP offer that sets the 1078 port number to zero in the related "m=" line that describes the file 1079 transfer (see Section 8.2 of RFC 3264 [RFC3264]). This SDP offer 1080 MUST conform with the requirements expressed in Section 8.2.2. The 1081 'file-transfer-id' attribute MUST be the same that identifies the 1082 ongoing transfer. Then the file receiver sends this SDP offer to the 1083 file sender. 1085 File sender File receiver 1086 | | 1087 |\ | 1088 | \ MSRP SEND | 1089 | \ Failure-Report: yes | 1090 | \ | 1091 | \ | 1092 | \ | 1093 | \ | 1094 | \ | 1095 | \ | 1096 | MSRP 413 |<-abort 1097 |<-----------------------| 1098 | \ (#) | 1099 | +----------->| 1100 | re-INVITE (SDP offer) | 1101 |<-----------------------| 1102 | SIP 200 OK (SDP answer)| 1103 |----------------------->| 1104 | SIP ACK | 1105 |<-----------------------| 1106 | | 1108 Figure 5: File receiver aborts an ongoing file transfer. Failure- 1109 Report set to a value different than "no" in MSRP 1111 In another scenario, depicted in Figure 6, an ongoing file transfer 1112 is taking place, where the MSRP SEND request contains a Failure- 1113 Report header set to the value "no". When the file receiver wants to 1114 abort the ongoing transfer, it MUST close MSRP session by generating 1115 a new SDP offer that sets the port number to zero in the related "m=" 1116 line that describes the file transfer (see Section 8.2 of RFC 3264 1117 [RFC3264]). This SDP offer MUST conform with the requirements 1118 expressed in Section 8.2.2. The 'file-transfer-id' attribute MUST be 1119 the same that identifies the ongoing transfer. Then the file 1120 receiver sends this SDP offer to the file sender. 1122 File sender File receiver 1123 | | 1124 |\ | 1125 | \ MSRP SEND | 1126 | \ Failure-Report: no | 1127 | \ | 1128 | \ | 1129 | \ | 1130 | \ | 1131 | \ | 1132 | \ | 1133 | re-INVITE (SDP offer) |<-abort 1134 |<-----------------------| 1135 | \ (#) | 1136 | +----------->| 1137 | MSRP 200 | 1138 |<-----------------------| 1139 | SIP 200 OK (SDP answer)| 1140 |----------------------->| 1141 | SIP ACK | 1142 |<-----------------------| 1143 | | 1145 Figure 6: File receiver aborts an ongoing file transfer. Failure- 1146 Report set to "no" in MSRP 1148 A file sender that receives an SDP offer setting the port number to 1149 zero in the related "m=" line for file transfer, first, if an ongoing 1150 MSRP SEND request is being transmitted, it aborts the MSRP message by 1151 including the '#' character in the continuation field of the end-line 1152 of a SEND request, according to the MSRP procedures (see Section 7.1 1153 of RFC 4975 [RFC4975]). Since a file is transmitted as one MSRP 1154 message, aborting the MSRP message effectively aborts the file 1155 transfer. Then the file sender creates an SDP answer according to 1156 the procedures of the SDP offer/answer (RFC 3264 [RFC3264]). This 1157 SDP answer MUST conform with the requirements of Section 8.3.2. Then 1158 the file sender sends this SDP answer to the file receiver. 1160 8.5. Indicating File Transfer Offer/Answer Capability 1162 The SDP Offer/Answer Model [RFC3264] provides provisions for 1163 indicating a capability to another endpoint (see Section 9 of RFC 1164 3264 [RFC3264]). The mechanism assumes a high-level protocol, such 1165 as SIP [RFC3261], that provides a capability query (such as a SIP 1166 OPTIONS request). RFC 3264 [RFC3264] indicates how to build the SDP 1167 that is included in the response to such capability query. As such, 1168 RFC 3264 indicates that an endpoint builds an SDP body that contains 1169 an "m=" line containing the media type (message, for MSRP). An 1170 endpoint that implements the procedures specified in this document 1171 SHOULD also add a 'file-selector' media attribute for the "m=message" 1172 line. The 'file-selector' media attribute MUST be empty, i.e., it 1173 MUST NOT contain any selector. The endpoint MUST NOT add any of the 1174 other file attributes defined in this specification. 1176 8.6. Re-usage of Existing "m=" Lines in SDP 1178 The SDP Offer/Answer Model [RFC3264] provides rules that allow SDP 1179 offerers and answerers to modify an existing media line, i.e., re-use 1180 an existing media line with different attributes. The same is also 1181 possible when SDP signals a file transfer operation according to the 1182 rules of this memo. Therefore, the procedures defined in RFC 3264 1183 [RFC3264], in particular those defined in Section 8.3, MUST apply for 1184 file transfer operations. An endpoint that wants to re-use an 1185 existing "m=" line to start the file transfer of another file creates 1186 a different 'file-selector' attribute and selects a new globally 1187 unique random value of the 'file-transfer-id' attribute. 1189 If the file offerer re-sends an SDP offer with a port different than 1190 zero, then the 'file-transfer-id' attribute determines whether a new 1191 file transfer will start or whether the file transfer does not need 1192 to start. If the SDP answerer accepts the SDP, then file transfer 1193 starts from the indicated octet (if a 'file-range' attribute is 1194 present). 1196 8.7. MSRP Usage 1198 The file transfer service specified in this document uses "m=" lines 1199 in SDP to describe the unidirectional transfer of a file. 1200 Consequently, each MSRP session established following the procedures 1201 in Section 8.2 and Section 8.3 is only used to transfer a single 1202 file. So, senders MUST only use the dedicated MSRP session to send 1203 the file described in the SDP offer or answer. That is, senders MUST 1204 NOT send additional files over the same MSRP session. 1206 File transfer may be accomplished using a new multimedia session 1207 established for the purpose. Alternatively a file transfer may be 1208 conducted within an existing multimedia session, without regard for 1209 the media in use within that session. Of particular note, file 1210 transfer may be done within a multimedia session containing an MSRP 1211 session used for regular instant messaging. If file transfer is 1212 initiated within an existing multimedia session, the SDP offerer MUST 1213 NOT reuse an existing "m=" line that is still being used by MSRP 1214 (either regular MSRP for instant messaging or an ongoing file 1215 transfer). Rather it MUST add an addtional "m=" line or else reuse 1216 an "m=" line that is no longer being used. 1218 Additionally, implementations according to this specification MUST 1219 include a single file in a single MSRP message. Notice that the MSRP 1220 specification defines "MSRP message" as a complete unit of MIME or 1221 text content, which can be split and delivered in more than one MSRP 1222 request; each of these portions of the complete message is called a 1223 "chunk". So, it is still valid to send a file in several chunks, but 1224 from the MSRP point of view, all the chunks together form an MSRP 1225 message: the CPIM message that wraps the file. When chunking is 1226 used, it should be noticed that MSRP does not require to wait for a 1227 200-class response for a chunk before sending the following one. 1228 Therefore, it is valid to send pipelined MSRP SEND requests 1229 containing chunks of the same MSRP message (the file). Section 9.1 1230 contains an example of a file transfer using pipelined MSRP requests. 1232 The MSRP specification [RFC4975] defines a 'max-size' SDP attribute. 1233 This attribute specifies the maximum number of octets of an MSRP 1234 message that the creator of the SDP is willing to receive (notice 1235 once more the definition of "MSRP message"). File receivers MAY add 1236 a 'max-size' attribute to the MSRP "m=" line that specifies the file, 1237 indicating the maximum number of octets of an MSRP message. File 1238 senders MUST NOT exceed the 'max-size' limit for any message sent in 1239 the resulting session. 1241 In the absence of a 'file-range' attribute in the SDP, the MSRP file 1242 transfer MUST start with the first octet of the file and end with the 1243 last octet (i.e., the whole file is transferred). If a 'file-range' 1244 attribute is present in SDP, the file sender application MUST extract 1245 the indicated range of octets from the file (start and stop offset 1246 octets, both inclusive). Then the file sender application MAY wrap 1247 those octets in an appropriate wrapper. MSRP mandates 1248 implementations to implement the message/cpim wrapper [RFC3862]. 1249 Usage of a wrapper is negotiated in the SDP (see Section 8.6 in RFC 1250 4975 [RFC4975]). Last, the file sender application delivers the 1251 content (e.g., the message/cpim body) to MSRP for transportation. 1252 MSRP will consider the delivered content as a whole message, and will 1253 start numbering bytes with the number 1. 1255 Note that the default content disposition of MSRP bodies is 'render'. 1257 When MSRP is used to transfer files, the MSRP Content-Disposition 1258 header can also take the value 'attachment' as indicated in 1259 Section 7. 1261 Once the file transfer is completed, the file sender SHOULD close the 1262 MSRP session and MUST behave according to the MSRP [RFC4975] 1263 procedures with respect to closing MSRP sessions. Note that MSRP 1264 session management is not related to TCP connection management. As a 1265 matter of fact, MSRP allows multiple MSRP sessions to share the same 1266 TCP connection. 1268 8.8. Considerations about the 'file-icon' attribute 1270 This specification allows a file sender to include a small preview of 1271 an image file: an icon. A 'file-icon' attribute contains a CID URL 1272 [RFC2392] pointing to an additional body that contains the actual 1273 icon. Since the icon is sent as a separate body along the SDP body, 1274 the file sender MUST wrap the SDP body and the icon bodies in a MIME 1275 multipart/related body. Therefore, implementations according to this 1276 specification MUST implement the multipart/related MIME type 1277 [RFC2387]. When creating a multipart/related MIME wrapper, the SDP 1278 body MUST be the root body, which according to RFC 2387 [RFC2387] is 1279 identified as the first body in the multipart/related MIME wrapper or 1280 explicitly identified by the 'start' parameter. According to RFC 1281 2387 [RFC2387], the 'type' parameter MUST be present and point to the 1282 root body, i.e., the SDP body. 1284 Assume that an endpoint behaving according to this specification 1285 tries to send a file to a remote endpoint that neither implements 1286 this specification nor implements multipart MIME bodies. The file 1287 sender sends an SDP offer that contains a multipart/related MIME body 1288 that includes an SDP body part and an icon body part. The file 1289 receiver, not supporting multipart MIME types, will reject the SDP 1290 offer via a higher protocol mechanism (e.g., SIP). In this case, it 1291 is RECOMMENDED that the file sender removes the icon body part, 1292 creates a single SDP body (i.e., without multipart MIME) and re-sends 1293 the SDP offer again. This provides some backwards compatibility with 1294 file receives that do not implement this specification and increases 1295 the chances of getting the SDP accepted at the file receiver. 1297 Since the icon is sent as part of the signaling, it is RECOMMENDED to 1298 keep the size of icons restricted to the minimum number of octets 1299 that provide significance. 1301 9. Examples 1302 9.1. Offerer sends a file to the Answerer 1304 This section shows an example flow for a file transfer scenario. The 1305 example assumes that SIP [RFC3261] is used to transport the SDP 1306 offer/answer exchange, although the SIP details are briefly shown for 1307 the sake of brevity. 1309 Alice, the SDP offerer, wishes to send an image file to Bob (the 1310 answerer). Alice's User Agent Client (UAC) creates a unidirectional 1311 SDP offer that contains the description of the file that she wants to 1312 send to Bob's User Agent Server (UAS). The description also includes 1313 an icon representing the contents of the file to be transferred. The 1314 sequence flow is shown in Figure 7. 1316 Alice's UAC Bob's UAS 1317 | | 1318 |(1) (SIP) INVITE | 1319 |----------------------->| 1320 |(2) (SIP) 200 OK | 1321 |<-----------------------| 1322 |(3) (SIP) ACK | 1323 |----------------------->| 1324 | | 1325 |(4) (MSRP) SEND (chunk) | 1326 |----------------------->| 1327 |(5) (MSRP) SEND (chunk) | 1328 |----------------------->| 1329 |(6) (MSRP) 200 OK | 1330 |<-----------------------| 1331 |(7) (MSRP) 200 OK | 1332 |<-----------------------| 1333 | | 1334 |(8) (SIP) BYE | 1335 |----------------------->| 1336 |(9) (SIP) 200 OK | 1337 |<-----------------------| 1338 | | 1339 | | 1341 Figure 7: Flow diagram of an offerer sending a file to an answerer 1343 F1: Alice constructs an SDP description of the file to be sent and 1344 attaches it to a SIP INVITE request addressed to Bob. 1346 INVITE sip:bob@example.com SIP/2.0 1347 To: Bob 1348 From: Alice ;tag=1928301774 1349 Call-ID: a84b4c76e66710 1350 CSeq: 1 INVITE 1351 Max-Forwards: 70 1352 Date: Sun, 21 May 2006 13:02:03 GMT 1353 Contact: 1354 Content-Type: multipart/related; type="application/sdp"; 1355 boundary="boundary71" 1356 Content-Length: [length] 1358 --boundary71 1359 Content-Type: application/sdp 1360 Content-Length: [length of SDP] 1362 v=0 1363 o=alice 2890844526 2890844526 IN IP4 alicepc.example.com 1364 s= 1365 c=IN IP4 alicepc.example.com 1366 t=0 0 1367 m=message 7654 TCP/MSRP * 1368 i=This is my latest picture 1369 a=sendonly 1370 a=accept-types:message/cpim 1371 a=accept-wrapped-types:* 1372 a=path:msrp://alicepc.example.com:7654/jshA7we;tcp 1373 a=file-selector:name:"My cool picture.jpg" type:image/jpeg 1374 size:4092 hash:sha-1: 1375 72:24:5F:E8:65:3D:DA:F3:71:36:2F:86:D4:71:91:3E:E4:A2:CE:2E 1376 a=file-transfer-id:Q6LMoGymJdh0IKIgD6wD0jkcfgva4xvE 1377 a=file-disposition:render 1378 a=file-date:creation:"Mon, 15 May 2006 15:01:31 +0300" 1379 a=file-icon:cid:id2@alicepc.example.com 1381 --boundary71 1382 Content-Type: image/jpeg 1383 Content-Transfer-Encoding: binary 1384 Content-ID: 1385 Content-Length: [length of image] 1386 Content-Disposition: icon 1388 [...small preview icon of the file...] 1390 --boundary71-- 1392 Figure 8: INVITE request containing an SDP offer for file transfer 1393 NOTE: The Content-Type header field and the 'file-selector' 1394 attribute in the above figure are split in several lines for 1395 formatting purposes. Real implementations will encode it in a 1396 single line. 1398 From now on we omit the SIP details for the sake of brevity. 1400 F2: Bob receives the INVITE request, inspects the SDP offer and 1401 extracts the icon body, checks the creation date and file size, and 1402 decides to accept the file transfer. So Bob creates the following 1403 SDP answer: 1405 v=0 1406 o=bob 2890844656 2890844656 IN IP4 bobpc.example.com 1407 s= 1408 c=IN IP4 bobpc.example.com 1409 t=0 0 1410 m=message 8888 TCP/MSRP * 1411 a=recvonly 1412 a=accept-types:message/cpim 1413 a=accept-wrapped-types:* 1414 a=path:msrp://bobpc.example.com:8888/9di4ea;tcp 1415 a=file-selector:name:"My cool picture.jpg" type:image/jpeg 1416 size:4092 hash:sha-1: 1417 72:24:5F:E8:65:3D:DA:F3:71:36:2F:86:D4:71:91:3E:E4:A2:CE:2E 1418 a=file-transfer-id:Q6LMoGymJdh0IKIgD6wD0jkcfgva4xvE 1420 Figure 9: SDP answer accepting the SDP offer for file transfer 1422 NOTE: The 'file-selector' attribute in the above figure is split 1423 in three lines for formatting purposes. Real implementations will 1424 encode it in a single line. 1426 F4: Alice opens a TCP connection to Bob and creates an MSRP SEND 1427 request. This SEND request contains the first chunk of the file. 1429 MSRP d93kswow SEND 1430 To-Path: msrp://bobpc.example.com:8888/9di4ea;tcp 1431 From-Path: msrp://alicepc.example.com:7654/iau39;tcp 1432 Message-ID: 12339sdqwer 1433 Byte-Range: 1-2048/4385 1434 Content-Type: message/cpim 1436 To: Bob 1437 From: Alice 1438 DateTime: 2006-05-15T15:02:31-03:00 1439 Content-Disposition: render; filename="My cool picture.jpg"; 1440 creation-date="Mon, 15 May 2006 15:01:31 +0300"; 1441 size=4092 1442 Content-Type: image/jpeg 1444 ... first set of bytes of the JPEG image ... 1445 -------d93kswow+ 1447 Figure 10: MSRP SEND request containing the first chunk of actual 1448 file 1450 F5: Alice sends the second and last chunk. Note that MSRP allows to 1451 send pipelined chunks, so there is no need to wait for the 200 (OK) 1452 response from the previous chunk. 1454 MSRP op2nc9a SEND 1455 To-Path: msrp://bobpc.example.com:8888/9di4ea;tcp 1456 From-Path: msrp://alicepc.example.com:7654/iau39;tcp 1457 Message-ID: 12339sdqwer 1458 Byte-Range: 2049-4385/4385 1459 Content-Type: message/cpim 1461 ... second set of bytes of the JPEG image ... 1462 -------op2nc9a$ 1464 Figure 11: MSRP SEND request containing the second chunk of actual 1465 file 1467 F6: Bob acknowledges the reception of the first chunk. 1469 MSRP d93kswow 200 OK 1470 To-Path: msrp://alicepc.example.com:7654/iau39;tcp 1471 From-Path: msrp://bobpc.example.com:8888/9di4ea;tcp 1472 Byte-Range: 1-2048/4385 1473 -------d93kswow$ 1474 Figure 12: MSRP 200 OK response 1476 F7: Bob acknowledges the reception of the second chunk. 1478 MSRP op2nc9a 200 OK 1479 To-Path: msrp://alicepc.example.com:7654/iau39;tcp 1480 From-Path: msrp://bobpc.example.com:8888/9di4ea;tcp 1481 Byte-Range: 2049-4385/4385 1482 -------op2nc9a$ 1484 Figure 13: MSRP 200 OK response 1486 F8: Alice terminates the SIP session by sending a SIP BYE request. 1488 F9: Bob acknowledges the reception of the BYE request and sends a 200 1489 (OK) response. 1491 9.2. Offerer requests a file from the Answerer and second file transfer 1493 In this example Alice, the SDP offerer, first wishes to fetch a file 1494 from Bob, the SDP answerer. Alice knows that Bob has a specific file 1495 she wants to download. She has learned the hash of the file by some 1496 out-of-band mechanism. The hash selector is enough to produce a file 1497 selector that points to the specific file. So, Alice creates an SDP 1498 offer that contains the file descriptor. Bob accepts the file 1499 transfer and sends the file to Alice. When Alice has completely 1500 received Bob's file, she intends to send a new image file to Bob. 1501 Therefore Alice re-uses the existing SDP media line with different 1502 attributes and updates the description of the new file she wants to 1503 send to Bob's User Agent Server (UAS). In particular, Alice creates 1504 a new file transfer identifier since this is a new file transfer 1505 operation. Figure 14 shows the sequence flow. 1507 Alice's UAC Bob's UAS 1508 | | 1509 |(1) (SIP) INVITE | 1510 |----------------------->| 1511 |(2) (SIP) 200 OK | 1512 |<-----------------------| 1513 |(3) (SIP) ACK | 1514 |----------------------->| 1515 | | 1516 |(4) (MSRP) SEND (file) | 1517 |<-----------------------| 1518 |(5) (MSRP) 200 OK | 1519 |----------------------->| 1520 | | 1521 |(6) (SIP) INVITE | 1522 |----------------------->| 1523 |(7) (SIP) 200 OK | 1524 |<-----------------------| 1525 |(8) (SIP) ACK | 1526 |----------------------->| 1527 | | 1528 |(9) (MSRP) SEND (file) | 1529 |----------------------->| 1530 |(10) (MSRP) 200 OK | 1531 |<-----------------------| 1532 | | 1533 |(11) (SIP) BYE | 1534 |<-----------------------| 1535 |(12) (SIP) 200 OK | 1536 |----------------------->| 1537 | | 1538 | | 1540 Figure 14: Flow diagram of an offerer requesting a file from the 1541 answerer and then sending a file to the answer 1543 F1: Alice constructs an SDP description of the file she wants to 1544 receive and attaches the SDP offer to a SIP INVITE request addressed 1545 to Bob. 1547 INVITE sip:bob@example.com SIP/2.0 1548 To: Bob 1549 From: Alice ;tag=1928301774 1550 Call-ID: a84b4c76e66710 1551 CSeq: 1 INVITE 1552 Max-Forwards: 70 1553 Date: Sun, 21 May 2006 13:02:03 GMT 1554 Contact: 1555 Content-Type: application/sdp 1556 Content-Length: [length of SDP] 1558 v=0 1559 o=alice 2890844526 2890844526 IN IP4 alicepc.example.com 1560 s= 1561 c=IN IP4 alicepc.example.com 1562 t=0 0 1563 m=message 7654 TCP/MSRP * 1564 a=recvonly 1565 a=accept-types:message/cpim 1566 a=accept-wrapped-types:* 1567 a=path:msrp://alicepc.example.com:7654/jshA7we;tcp 1568 a=file-selector:hash:sha-1: 1569 72:24:5F:E8:65:3D:DA:F3:71:36:2F:86:D4:71:91:3E:E4:A2:CE:2E 1570 a=file-transfer-id:aCQYuBRVoUPGVsFZkCK98vzcX2FXDIk2 1572 Figure 15: INVITE request containing an SDP offer for file transfer 1574 NOTE: The 'file-selector' attribute in the above figure is split 1575 in two lines for formatting purposes. Real implementations will 1576 encode it in a single line. 1578 From now on we omit the SIP details for the sake of brevity. 1580 F2: Bob receives the INVITE request, inspects the SDP offer, computes 1581 the file descriptor and finds a local file whose hash equals the one 1582 indicated in the SDP. Bob accepts the file transfer and creates an 1583 SDP answer as follows: 1585 v=0 1586 o=bob 2890844656 2890855439 IN IP4 bobpc.example.com 1587 s= 1588 c=IN IP4 bobpc.example.com 1589 t=0 0 1590 m=message 8888 TCP/MSRP * 1591 a=sendonly 1592 a=accept-types:message/cpim 1593 a=accept-wrapped-types:* 1594 a=path:msrp://bobpc.example.com:8888/9di4ea;tcp 1595 a=file-selector:type:image/jpeg hash:sha-1: 1596 72:24:5F:E8:65:3D:DA:F3:71:36:2F:86:D4:71:91:3E:E4:A2:CE:2E 1597 a=file-transfer-id:aCQYuBRVoUPGVsFZkCK98vzcX2FXDIk2 1599 Figure 16: SDP answer accepting the SDP offer for file transfer 1601 NOTE: The 'file-selector' attribute in the above figure is split 1602 in two lines for formatting purposes. Real implementations will 1603 encode it in a single line. 1605 F4: Alice opens a TCP connection to Bob. Bob then creates an MSRP 1606 SEND request that contains the file. 1608 MSRP d93kswow SEND 1609 To-Path: msrp://alicepc.example.com:7654/jshA7we;tcp 1610 From-Path: msrp://bobpc.example.com:8888/9di4ea;tcp 1611 Message-ID: 12339sdqwer 1612 Byte-Range: 1-2027/2027 1613 Content-Type: message/cpim 1615 To: Bob 1616 From: Alice 1617 DateTime: 2006-05-15T15:02:31-03:00 1618 Content-Disposition: render; filename="My cool photo.jpg"; 1619 creation-date="Mon, 15 May 2006 15:01:31 +0300"; 1620 modification-date="Mon, 15 May 2006 16:04:53 +0300"; 1621 read-date="Mon, 16 May 2006 09:12:27 +0300"; 1622 size=1931 1623 Content-Type: image/jpeg 1625 ...binary JPEG image... 1626 -------d93kswow$ 1628 Figure 17: MSRP SEND request containing the actual file 1630 F5: Alice acknowledges the reception of the SEND request. 1632 MSRP d93kswow 200 OK 1633 To-Path: msrp://bobpc.example.com:8888/9di4ea;tcp 1634 From-Path: msrp://alicepc.example.com:7654/jshA7we;tcp 1635 Byte-Range: 1-2027/2027 1636 -------d93kswow$ 1638 Figure 18: MSRP 200 OK response 1640 F6: Alice re-uses the existing SDP media line inserting the 1641 description of the file to be sent and attaches it to a SIP re-INVITE 1642 request addressed to Bob. Alice reuses the TCP port number for the 1643 MSRP stream, but changes the MSRP session and the 'file-transfer-id' 1644 value according to this specification. 1646 INVITE sip:bob@example.com SIP/2.0 1647 To: Bob ;tag=1928323431 1648 From: Alice ;tag=1928301774 1649 Call-ID: a84b4c76e66710 1650 CSeq: 2 INVITE 1651 Max-Forwards: 70 1652 Date: Sun, 21 May 2006 13:02:33 GMT 1653 Contact: 1654 Content-Type: multipart/related; type="application/sdp"; 1655 boundary="boundary71" 1656 Content-Length: [length of multipart] 1658 --boundary71 1659 Content-Type: application/sdp 1660 Content-Length: [length of SDP] 1662 v=0 1663 o=alice 2890844526 2890844527 IN IP4 alicepc.example.com 1664 s= 1665 c=IN IP4 alicepc.example.com 1666 t=0 0 1667 m=message 7654 TCP/MSRP * 1668 i=This is my latest picture 1669 a=sendonly 1670 a=accept-types:message/cpim 1671 a=accept-wrapped-types:* 1672 a=path:msrp://alicepc.example.com:7654/iau39;tcp 1673 a=file-selector:name:"sunset.jpg" type:image/jpeg 1674 size:4096 hash:sha-1: 1675 58:23:1F:E8:65:3B:BC:F3:71:36:2F:86:D4:71:91:3E:E4:B1:DF:2F 1676 a=file-transfer-id:ZVE8MfI9mhAdZ8GyiNMzNN5dpqgzQlCO 1677 a=file-disposition:render 1678 a=file-date:creation:"Sun, 21 May 2006 13:02:15 +0300" 1679 a=file-icon:cid:id3@alicepc.example.com 1681 --boundary71 1682 Content-Type: image/jpeg 1683 Content-Transfer-Encoding: binary 1684 Content-ID: 1685 Content-Length: [length of image] 1686 Content-Disposition: icon 1688 [..small preview icon...] 1690 --boundary71-- 1692 Figure 19: Reuse of the SDP in a second file transfer 1694 NOTE: The Content-Type header field and the 'file-selector' 1695 attribute in the above figure are split in several lines for 1696 formatting purposes. Real implementations will encode it in a 1697 single line. 1699 F7: Bob receives the re-INVITE request, inspects the SDP offer and 1700 extracts the icon body, checks the creation date and the file size, 1701 and decides to accept the file transfer. So Bob creates an SDP 1702 answer where he reuses the same TCP port number, but changes his MSRP 1703 session, according to the procedures of this specification. 1705 v=0 1706 o=bob 2890844656 2890855440 IN IP4 bobpc.example.com 1707 s= 1708 c=IN IP4 bobpc.example.com 1709 t=0 0 1710 m=message 8888 TCP/MSRP * 1711 a=recvonly 1712 a=accept-types:message/cpim 1713 a=accept-wrapped-types:* 1714 a=path:msrp://bobpc.example.com:8888/eh10dsk;tcp 1715 a=file-selector:name:"sunset.jpg" type:image/jpeg 1716 size:4096 hash:sha-1: 1717 58:23:1F:E8:65:3B:BC:F3:71:36:2F:86:D4:71:91:3E:E4:B1:DF:2F 1718 a=file-transfer-id:ZVE8MfI9mhAdZ8GyiNMzNN5dpqgzQlCO 1719 a=file-disposition:render 1721 Figure 20: SDP answer accepting the SDP offer for file transfer 1723 NOTE: The 'file-selector' attribute in the above figure is split 1724 in three lines for formatting purposes. Real implementations will 1725 encode it in a single line. 1727 F9: If a TCP connection towards Bob is already open, Alice re-uses 1728 that TCP connection to send an MSRP SEND request that contains the 1729 file. 1731 MSRP d95ksxox SEND 1732 To-Path: msrp://bobpc.example.com:8888/eh10dsk;tcp 1733 From-Path: msrp://alicepc.example.com:7654/iau39;tcp 1734 Message-ID: 13449sdqwer 1735 Byte-Range: 1-2027/2027 1736 Content-Type: message/cpim 1738 To: Bob 1739 From: Alice 1740 DateTime: 2006-05-21T13:02:15-03:00 1741 Content-Disposition: render; filename="Sunset.jpg"; 1742 creation-date="Sun, 21 May 2006 13:02:15 -0300"; 1743 size=1931 1744 Content-Type: image/jpeg 1746 ...binary JPEG image... 1747 -------d95ksxox+ 1749 Figure 21: MSRP SEND request containing the actual file 1751 F10: Bob acknowledges the reception of the SEND request. 1753 MSRP d95ksxox 200 OK 1754 To-Path: msrp://alicepc.example.com:7654/iau39;tcp 1755 From-Path: msrp://bobpc.example.com:8888/eh10dsk;tcp 1756 Byte-Range: 1-2027/2027 1757 -------d95ksxox$ 1759 Figure 22: MSRP 200 OK response 1761 F11: Then Bob terminates the SIP session by sending a SIP BYE 1762 request. 1764 F12: Alice acknowledges the reception of the BYE request and sends a 1765 200 (OK) response. 1767 9.3. Example of a capability indication 1769 Alice sends an OPTIONS request to Bob (this request does not contain 1770 SDP). Bob answers with a 200 (OK) response that contain the SDP 1771 shown in Figure 24. The SDP indicates support for CPIM messages that 1772 can contain other MIME types. The maximum MSRP message size that the 1773 endpoint can receive is 20000 octets. The presence of the 'file- 1774 selector' attribute indicates support for the file transfer offer/ 1775 answer mechanism. 1777 Alice's UAC Bob's UAS 1778 | | 1779 |(1) (SIP) OPTIONS | 1780 |----------------------->| 1781 |(2) (SIP) 200 OK | 1782 | with SDP | 1783 |<-----------------------| 1784 | | 1785 | | 1787 Figure 23: Flow diagram of a capability request 1789 v=0 1790 o=bob 2890844656 2890855439 IN IP4 bobpc.example.com 1791 s=- 1792 c=IN IP4 bobpc.example.com 1793 t=0 0 1794 m=message 0 TCP/MSRP * 1795 a=accept-types:message/cpim 1796 a=accept-wrapped-types:* 1797 a=max-size:20000 1798 a=file-selector 1800 Figure 24: SDP of the 200 (OK) response to an OPTIONS request 1802 10. Security Considerations 1804 The SDP attributes defined in this specification identify a file to 1805 be transferred between two endpoints. An endpoint can offer to send 1806 the file to the other endpoint or request to receive the file from 1807 the other endpoint. In the former case, an attacker modifying those 1808 SDP attributes could cheat the receiver making it think that the file 1809 to be transferred was a different one. In the latter case, the 1810 attacker could make the sender send a different file than the one 1811 requested by the receiver. Consequently, it is RECOMMENDED that 1812 integrity protection be applied to the SDP session descriptions 1813 carrying the attributes specified in this specification. 1814 Additionally, it is RECOMMENDED that senders verify the properties of 1815 the file against the selectors that describe it. 1817 The descriptions of the files being transferred between endpoints may 1818 reveal information the endpoints may consider confidential. 1819 Therefore, it is RECOMMENDED that SDP session descriptions carrying 1820 the attributes specified in this specification are encrypted. 1822 TLS and S/MIME are the natural choices to provide offer/answer 1823 exchanges with integrity protection and confidentiality. 1825 When an SDP offer contains the description of a file to be sent or 1826 received, the SDP answerer MUST first authenticate the SDP offerer 1827 and then it MUST authorize the file transfer operation, typically 1828 according to a local policy. Typically these functions are 1829 integrated in the high-level protocol that carries SDP (e.g., SIP), 1830 and in the file transfer protocol (e.g., MSRP). If SIP [RFC3261] and 1831 MSRP [RFC4975] are used, the standard mechanisms for user 1832 authentication and authorization are sufficient. 1834 It is possible that a malicious or misbehaving implementation tries 1835 to exhaust the resources of the remote endpoint, e.g., the internal 1836 memory or the file system, by sending very large files. To protect 1837 from this attack, an SDP answer SHOULD first verify the identity of 1838 the SDP offerer, and perhaps only accept file transfers from trusted 1839 sources. Mechanisms to verify the identity of the file sender depend 1840 on the high-level protocol that carries the SDP, for example, SIP 1841 [RFC3261] and MSRP [RFC4975]. 1843 It is also RECOMMENDED that implementations take measures to avoid 1844 attacks on resource exhaustion, for example, by limiting the size of 1845 received files, verifying that there is enough space in the file 1846 system to store the file prior to its reception, or limiting the 1847 number of simultaneous file transfers. 1849 File receivers MUST also sanitize all input, such as the local file 1850 name, prior to making calls to the local file system to store a file. 1851 This is to prevent the existence of meaningful characters to the 1852 local operating system that could damage it. 1854 Once a file has been transferred the file receiver must take care of 1855 it. Typically file transfer is a commonly used mechanism for 1856 transmitting computer virus, spyware, and other types of malware. 1857 File receivers should apply all possible security technologies (e.g., 1858 antivirus, antispyware, etc.) to mitigate the risk of damage at their 1859 host. 1861 11. IANA Considerations 1863 This document instructs IANA to register a number of SDP attributes 1864 according to the following: 1866 11.1. Registration of new SDP attributes 1868 This memo provides instructions to IANA to register a number of media 1869 level only attributes in the Session Description Protocol Parameters 1870 registry [4]. The registration data, according to RFC 4566 [RFC4566] 1871 follows. 1873 Note to the RFC Editor: replace "RFC XXXX" with the RFC number of 1874 this specification. 1876 11.1.1. Registration of the file-selector attribute 1878 Contact: Miguel Garcia 1879 Phone: +34 91 339 1000 1880 Attribute name: file-selector 1881 Long-form attribute name: File Selector 1882 Type of attribute: media level only 1883 This attribute is subject to the charset attribute 1884 Description: This attribute unambiguously identify a file by 1885 indicating a combination of the 4-tuple composed of the name, 1886 size, type, and hash of the file. 1887 Specification: RFC XXXX 1889 11.1.2. Registration of the file-transfer-id attribute 1891 Contact: Miguel Garcia 1892 Phone: +34 91 339 1000 1893 Attribute name: file-transfer-id 1894 Long-form attribute name: File Transfer Identifier 1895 Type of attribute: media level only 1896 This attribute is subject to the charset attribute 1897 Description: This attribute contains a unique identifier of the 1898 file transfer operation within the session. 1899 Specification: RFC XXXX 1901 11.1.3. Registration of the file-disposition attribute 1903 Contact: Miguel Garcia 1904 Phone: +34 91 339 1000 1905 Attribute name: file-disposition 1906 Long-form attribute name: File Disposition 1907 Type of attribute: media level only 1908 This attribute is not subject to the charset attribute 1909 Description: This attribute provides a suggestion to the other 1910 endpoint about the intended disposition of the file 1911 Specification: RFC XXXX 1913 11.1.4. Registration of the file-date attribute 1915 Contact: Miguel Garcia 1916 Phone: +34 91 339 1000 1917 Attribute name: file-date 1918 Long-form attribute name: 1919 Type of attribute: media level only 1920 This attribute is not subject to the charset attribute 1921 Description: This attribute indicates the dates at which the file 1922 was created, modified, or last read. 1923 Specification: RFC XXXX 1925 11.1.5. Registration of the file-icon attribute 1927 Contact: Miguel Garcia 1928 Phone: +34 91 339 1000 1929 Attribute name: file-icon 1930 Long-form attribute name: File Icon 1931 Type of attribute: media level only 1932 This attribute is not subject to the charset attribute 1933 Description: For image files, this attribute contains a pointer to 1934 a body that includes a small preview icon representing the 1935 contents of the file to be transferred 1936 Specification: RFC XXXX 1938 11.1.6. Registration of the file-range attribute 1940 Contact: Miguel Garcia 1941 Phone: +34 91 339 1000 1942 Attribute name: file-range 1943 Long-form attribute name: File Range 1944 Type of attribute: media level only 1945 This attribute is not subject to the charset attribute 1946 Description: it contains the range of transferred octets of the 1947 file 1948 Specification: RFC XXXX 1950 12. Acknowledgements 1952 The authors would like to thank Mats Stille, Nancy Greene, Adamu 1953 Haruna, and Arto Leppisaari for discussing initial concepts described 1954 in this memo. Thanks to Pekka Kuure for reviewing initial versions 1955 this document and providing helpful comments. Joerg Ott, Jiwey Wang, 1956 Amitkumar Goel, Sudha Vs, Dan Wing, Juuso Lehtinen, Remi Denis- 1957 Courmont, Colin Perkins, Sudhakar An, Peter Saint-Andre, Jonathan 1958 Rosenberg, Eric Rescorla, Vikram Chhibber, Ben Campbell, Richard 1959 Barnes, and Chris Newman discussed and provided comments and 1960 improvements to this document. 1962 13. References 1964 13.1. Normative References 1966 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1967 Requirement Levels", BCP 14, RFC 2119, March 1997. 1969 [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1970 Extensions (MIME) Part One: Format of Internet Message 1971 Bodies", RFC 2045, November 1996. 1973 [RFC2183] Troost, R., Dorner, S., and K. Moore, "Communicating 1974 Presentation Information in Internet Messages: The 1975 Content-Disposition Header Field", RFC 2183, August 1997. 1977 [RFC2387] Levinson, E., "The MIME Multipart/Related Content-type", 1978 RFC 2387, August 1998. 1980 [RFC2392] Levinson, E., "Content-ID and Message-ID Uniform Resource 1981 Locators", RFC 2392, August 1998. 1983 [RFC3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1 1984 (SHA1)", RFC 3174, September 2001. 1986 [RFC3264] Rosenberg, J. and H. Schulzrinne, "An Offer/Answer Model 1987 with Session Description Protocol (SDP)", RFC 3264, 1988 June 2002. 1990 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1991 10646", STD 63, RFC 3629, November 2003. 1993 [RFC3851] Ramsdell, B., "Secure/Multipurpose Internet Mail 1994 Extensions (S/MIME) Version 3.1 Message Specification", 1995 RFC 3851, July 2004. 1997 [RFC3862] Klyne, G. and D. Atkins, "Common Presence and Instant 1998 Messaging (CPIM): Message Format", RFC 3862, August 2004. 2000 [RFC4566] Handley, M., Jacobson, V., and C. Perkins, "SDP: Session 2001 Description Protocol", RFC 4566, July 2006. 2003 [RFC4975] Campbell, B., Mahy, R., and C. Jennings, "The Message 2004 Session Relay Protocol (MSRP)", RFC 4975, September 2007. 2006 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2007 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2009 [RFC5322] Resnick, P., Ed., "Internet Message Format", RFC 5322, 2010 October 2008. 2012 13.2. Informational References 2014 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 2015 A., Peterson, J., Sparks, R., Handley, M., and E. 2016 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 2017 June 2002. 2019 [RFC4028] Donovan, S. and J. Rosenberg, "Session Timers in the 2020 Session Initiation Protocol (SIP)", RFC 4028, April 2005. 2022 [RFC4483] Burger, E., "A Mechanism for Content Indirection in 2023 Session Initiation Protocol (SIP) Messages", RFC 4483, 2024 May 2006. 2026 [RFC4976] Jennings, C., Mahy, R., and A. Roach, "Relay Extensions 2027 for the Message Sessions Relay Protocol (MSRP)", RFC 4976, 2028 September 2007. 2030 [I-D.ietf-rmt-flute-revised] 2031 Luby, M., Lehtonen, R., Roca, V., and T. Paila, "FLUTE - 2032 File Delivery over Unidirectional Transport", 2033 draft-ietf-rmt-flute-revised-06 (work in progress), 2034 September 2008. 2036 URIs 2038 [1] 2040 [2] 2042 [3] 2044 [4] 2046 Appendix A. Alternatives Considered 2048 The requirements are related to the description and negotiation of 2049 the session, not to the actual file transfer mechanism. Thus, it is 2050 natural that in order to meet them it is enough to define attribute 2051 extensions and usage conventions to SDP, while MSRP itself needs no 2052 extensions and can be used as it is. This is effectively the 2053 approach taken in this specification. Another goal has been to 2054 specify the SDP extensions in such a way that a regular MSRP endpoint 2055 which does not support them could still in some cases act as an 2056 endpoint in a file transfer session, albeit with a somewhat reduced 2057 functionality. 2059 In some ways the aim of this specification is similar to the aim of 2060 content indirection mechanism in the Session Initiation Protocol 2061 (SIP) [RFC4483]. Both mechanisms allow a user agent to decide 2062 whether or not to download a file based on information about the 2063 file. However, there are some differences. With content 2064 indirection, it is not possible for the other endpoint to explicitly 2065 accept or reject the file transfer. Also, it is not possible for an 2066 endpoint to request a file from another endpoint. Furthermore, 2067 content indirection is not tied to the context of a media session, 2068 which is sometimes a desirable property. Finally, content 2069 indirection typically requires some server infrastructure, which may 2070 not always be available. It is possible to use content indirection 2071 directly between the endpoints too, but in that case there is no 2072 definition for how it works for endpoints behind NATs. The level of 2073 requirements in implementations decides which solution meets the 2074 requirements. 2076 Based on the argumentation above, this document defines the SDP 2077 attribute extensions and usage conventions needed for meeting the 2078 requirements on file transfer services with the SDP offer/answer 2079 model, using MSRP as the transfer protocol within the session. 2081 In principle it is possible to use the SDP extensions defined here 2082 and replace MSRP with any other similar protocol that can carry 2083 MIME objects. This kind of specification can be written as a 2084 separate document if the need arises. Essentially, such protocol 2085 should be able to be negotiated on an SDP offer/answer exchange 2086 (RFC 3264 [RFC3264]), be able to describe the file to be 2087 transferred in SDP offer/answer exchange, be able to carry MIME 2088 objects between two endpoints, and use a reliable transport 2089 protocol (e.g., TCP). 2091 This specification defines a set of SDP attributes that describe a 2092 file to be transferred between two endpoints. The information needed 2093 to describe a file could be potentially encoded in a few different 2094 ways. The MMUSIC working group considered a few alternative 2095 approaches before deciding to use the encoding described in 2096 Section 6. In particular, the working group looked at the MIME 2097 'external-body' type and the use of a single SDP attribute or 2098 parameter. 2100 A MIME 'external-body' could potentially be used to describe the file 2101 to be transferred. In fact, many of the SDP parameters this 2102 specification defines are also supported by 'external-body' body 2103 parts. The MMUSIC working group decided not to use 'external-body' 2104 body parts because a number of existing offer/answer implementations 2105 do not support multipart bodies. 2107 The information carried in the SDP attributes defined in Section 6 2108 could potentially be encoded in a single SDP attribute. The MMUSIC 2109 working group decided not to follow this approach because it is 2110 expected that implementations support only a subset of the parameters 2111 defined in Section 6. Those implementations will be able to use 2112 regular SDP rules in order to ignore non-supported SDP parameters. 2113 If all the information was encoded in a single SDP attribute, those 2114 rules, which relate to backwards compatibility, would need to be 2115 redefined specifically for that parameter. 2117 Authors' Addresses 2119 Miguel A. Garcia-Martin 2120 Ericsson 2121 Calle Via de los Poblados 13 2122 Madrid, ES 28033 2123 Spain 2125 Email: miguel.a.garcia@ericsson.com 2127 Markus Isomaki 2128 Nokia 2129 Keilalahdentie 2-4 2130 Espoo 02150 2131 Finland 2133 Email: markus.isomaki@nokia.com 2135 Gonzalo Camarillo 2136 Ericsson 2137 Hirsalantie 11 2138 Jorvas 02420 2139 Finland 2141 Email: Gonzalo.Camarillo@ericsson.com 2142 Salvatore Loreto 2143 Ericsson 2144 Hirsalantie 11 2145 Jorvas 02420 2146 Finland 2148 Email: Salvatore.Loreto@ericsson.com 2150 Paul H. Kyzivat 2151 Cisco Systems 2152 1414 Massachusetts Avenue 2153 Boxborough, MA 01719 2154 USA 2156 Email: pkyzivat@cisco.com