idnits 2.17.1 draft-wood-tsvwg-saratoga-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with multicast IPv4 addresses in the document. If these are generic example addresses, they should be changed to use the 233.252.0.x range defined in RFC 5771 == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. 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 (September 22, 2010) is 4965 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 3309 (Obsoleted by RFC 4960) == Outdated reference: A later version (-10) exists of draft-ietf-ledbat-congestion-02 == Outdated reference: A later version (-09) exists of draft-wood-dtnrg-http-dtn-delivery-05 == Outdated reference: A later version (-14) exists of draft-wood-dtnrg-saratoga-07 Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Wood 3 Internet-Draft University of Surrey 4 Intended status: Experimental W. Eddy 5 Expires: March 26, 2011 MTI Systems 6 C. Smith 7 CSIRO 8 W. Ivancic 9 NASA 10 C. Jackson 11 SSTL 12 September 22, 2010 14 Saratoga: A Scalable File Transfer Protocol 15 draft-wood-tsvwg-saratoga-06 17 Abstract 19 This document specifies the Saratoga transfer protocol. Saratoga was 20 originally developed to efficiently transfer remote-sensing imagery 21 from a low-Earth-orbiting satellite constellation, but is useful for 22 many other scenarios, including ad-hoc peer-to-peer communications, 23 delay-tolerant networking, and grid computing. Saratoga is a simple, 24 lightweight, content dissemination protocol that builds on UDP, and 25 optionally uses UDP-Lite. Saratoga is intended for use when moving 26 files or streaming data between peers which may have only sporadic or 27 intermittent connectivity, and is capable of transferring very large 28 amounts of data reliably under adverse conditions. The Saratoga 29 protocol is designed to cope with highly asymmetric link or path 30 capacity between peers, and can support fully-unidirectional data 31 transfer if required. In scenarios with dedicated links, Saratoga 32 focuses on high link utilization to make the most of limited 33 connectivity times, while standard congestion control mechanisms can 34 be implemented for operation over shared links. Loss recovery is 35 implemented via a simple negative-ack ARQ mechanism. The protocol 36 specified in this document is considered to be appropriate for 37 experimental use on private IP networks. 39 Status of this Memo 41 This Internet-Draft is submitted to IETF in full conformance with the 42 provisions of BCP 78 and BCP 79. This document may not be modified, 43 and derivative works of it may not be created, except to format it 44 for publication as an RFC and to translate it into languages other 45 than English. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at http://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on March 26, 2011. 59 Copyright Notice 61 Copyright (c) 2010 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents 66 (http://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Background and Introduction . . . . . . . . . . . . . . . . . 4 77 2. Overview of Saratoga File Transfer . . . . . . . . . . . . . . 6 78 3. Optional Parts of Saratoga . . . . . . . . . . . . . . . . . . 11 79 4. Packet Types . . . . . . . . . . . . . . . . . . . . . . . . . 12 80 4.1. BEACON . . . . . . . . . . . . . . . . . . . . . . . . . . 14 81 4.2. REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . 18 82 4.3. METADATA . . . . . . . . . . . . . . . . . . . . . . . . . 21 83 4.4. DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 84 4.5. HOLESTOFILL . . . . . . . . . . . . . . . . . . . . . . . 27 85 5. The Directory Entry . . . . . . . . . . . . . . . . . . . . . 33 86 6. Behaviour of a Saratoga Peer . . . . . . . . . . . . . . . . . 35 87 6.1. Saratoga Transactions . . . . . . . . . . . . . . . . . . 35 88 6.2. Beacons . . . . . . . . . . . . . . . . . . . . . . . . . 39 89 6.3. Upper-Layer Interface . . . . . . . . . . . . . . . . . . 39 90 6.4. Inactivity Timer . . . . . . . . . . . . . . . . . . . . . 39 91 7. Mailing list . . . . . . . . . . . . . . . . . . . . . . . . . 40 92 8. Security Considerations . . . . . . . . . . . . . . . . . . . 40 93 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 41 94 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 41 95 11. A Note on Naming . . . . . . . . . . . . . . . . . . . . . . . 42 96 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 97 12.1. Normative References . . . . . . . . . . . . . . . . . . . 42 98 12.2. Informative References . . . . . . . . . . . . . . . . . . 42 99 Appendix A. Timestamp/Nonce field considerations . . . . . . . . 44 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 45 102 1. Background and Introduction 104 Saratoga is a file transfer and content dissemination protocol 105 capable of efficiently sending both small and very large files as 106 well as streaming continuous content. Saratoga was originally 107 designed for the purpose of large file transfer from small low-Earth- 108 orbit satellites. It has been used in daily operations since 2004 to 109 move mission imaging data files on the order of several hundred 110 megabytes each from the Disaster Monitoring Constellation (DMC) 111 remote-sensing satellites to ground stations. 113 The DMC satellites, built at the University of Surrey by Surrey 114 Satellite Technology Ltd (SSTL), all use IP for payload 115 communications and delivery of Earth imagery. At the time of this 116 writing in September 2010, seven DMC satellites have been launched 117 into orbit, five of those are currently operational in orbit, and two 118 further DMC satellites are being readied for launch. The DMC 119 satellites use Saratoga to provide Earth imagery under the aegis of 120 the International Charter on Space and Major Disasters. A pass of 121 connectivity between a satellite and ground station offers an 8-12 122 minute time window in which to transfer imagery files using a minimum 123 of an 8.1 Mbps downlink and a 9.6 kbps uplink. The latest 124 operational DMC satellites have faster downlinks, capable of 20, 40 125 or 80 Mbps. Newer satellites are expected to provide 200 Mbps or 126 more, without significant increases in uplink rates. This high 127 degree of asymmetry, and need to fully utilize the available downlink 128 capacity to move the volume of data required within the limited time 129 available, motivates much of Saratoga's design. 131 Further details on how these DMC satellites use IP to communicate 132 with the ground and the terrestrial Internet are discussed in other 133 documents [Hogie05][Wood07a][Ivancic10]. 135 Store-and-forward delivery relies on reliable hop-by-hop transfers of 136 files, removing the need for the final receiver to talk to the 137 original sender across long delays and allowing for the possibility 138 that an end-to-end path may never exist between sender and receiver 139 at any given time. Use of store-and-forward hop-by-hop delivery is 140 typical of scenarios in space exploration for both near-Earth and 141 deep-space missions, and useful for other scenarios, such as 142 underwater networking, ad-hoc sensor networks, and some message- 143 ferrying relay scenarios. Saratoga is intended to be useful for 144 relaying data in these scenarios, and can optionally also be used to 145 carry the Bundle Protocol "bundles" that is proposed for use in Delay 146 and Disruption-Tolerant Networking (DTN) by the IRTF DTN Research 147 Group [RFC5050]. This has been tested from orbit using the UK-DMC 148 satellite [Ivancic10]. How Saratoga can optionally function as a 149 "bundle convergence layer" alongside a DTN bundle agent is specified 150 in a companion document [I-D.wood-dtnrg-saratoga]. 152 High link utilization is important during periods of limited 153 connectivity. Given that Saratoga was originally developed for 154 scheduled peer-to-peer communications over dedicated links in private 155 networks, where each application has the entire link for the duration 156 of its transfer, early Saratoga implementations deliberately lack any 157 form of congestion control and send at line rate to maximise 158 throughput and link utilisation. Newer implementations may perform 159 TCP-Friendly Rate Control (TFRC) [RFC5348] or other congestion 160 control mechanisms such as LEDBAT [I-D.ietf-ledbat-congestion], if 161 appropriate for the environment, and where simultaneous sharing of 162 capacity with other traffic and applications is required. 164 Saratoga contains a Selective Negative Acknowledgement (SNACK) 165 mechanism to provide reliable retransmission of data. This is 166 intended to correct losses of corrupted link-layer frames due to 167 channel noise over a space link. Packet losses in the DMC are due to 168 corruption introducing non-recoverable errors in the frame. The DMC 169 design uses point-to-point links and scheduling of applications in 170 order, so that the link is dedicated to one application transfer at a 171 time, meaning that packet loss cannot be due to congestion when 172 applications compete for link capacity simultaneously. In other 173 wireless environments that may be shared by many nodes and 174 applications, allocation of channel resources to nodes becomes a MAC- 175 layer function. Forward Error Coding (FEC) to get the most reliable 176 transmission through a channel is best left near the physical layer 177 so that it can be tailored for the channel. Use of FEC complements 178 Saratoga's transport-level negative-acknowledgement approach to 179 provide a reliable ARQ mechanism [RFC3366]. 181 Saratoga is scalable in that it is capable of efficiently 182 transferring small or large files, by choosing a width of file offset 183 descriptor appropriate for the filesize, and advertising accepted 184 offset descriptor sizes. 16-bit, 32-bit, 64-bit and 128-bit 185 descriptors can be selected, for maximum file sizes of 64KiB-1, 186 4GiB-1, 2^64-1 and 2^128-1 octets. Earth imaging files currently 187 transferred by Saratoga are mostly up to a few gigabytes in size. 188 Some implementations do transfer more than 4 GiB in size, and so 189 require offset descriptors larger than 32 bits. We expect that a 190 128-bit descriptor will satisfy all future needs, but we expect 191 current implementations to only support up to 32-bit or 64-bit 192 descriptors, depending on their application needs. The 16-bit 193 descriptor is useful for small messages, including messages from 194 8-bit devices, and is always supported. The 128-bit descriptor is 195 useful for moving very large files stored on a 128-bit filesystem, 196 such as on OpenSolaris ZFS. 198 Saratoga can be used with either IPv4 or IPv6. Compatibility between 199 Saratoga and the wide variety of links that can already carry IP 200 traffic is assured. 202 Saratoga was originally implemented as outlined in [Jackson04], but 203 the specification given here differs substantially, as we have added 204 a number of features, while cleaning up the initial Saratoga 205 specification. The original Saratoga code uses a version number of 206 0, while code that implements this version of the protocol advertises 207 a version number of 1. Further discussion of the history and 208 development of Saratoga is given in [Wood07b]. 210 This document contains an overview of the transfer process and 211 transactions using Saratoga in Section 2, followed by a formal 212 definition of the packet types used by Saratoga in Section 4, and the 213 details of the various protocol mechanisms in Section 6. 215 Here, Saratoga transaction types are labelled with underscores around 216 lowercase names (such as a "_get_" transaction), while Saratoga 217 packet types are labelled in all capitals (such as a "REQUEST" 218 packet) in order to distinguish between the two. 220 The remainder of this specification uses 'file' as a shorthand for 221 'binary object', which may be a DTN bundle, or other type of data. 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 225 document are to be interpreted as described in RFC 2119. [RFC2119] 227 2. Overview of Saratoga File Transfer 229 Saratoga is a peer-to-peer protocol in the sense that multiple files 230 may be transferred in both directions simultaneously between two 231 communicating Saratoga peers, and there is not intended to be a 232 strict client-to-server relationship. 234 Saratoga nodes can act as simple file servers. Saratoga supports 235 several types of operations on files including "pull" downloads, 236 "push" uploads, directory listing, and deletion requests. Each 237 operation is handled as a distinct "transaction" between the peers. 239 Saratoga nodes MAY advertise their presence, capabilities, and 240 desires by sending BEACON packets. These BEACONs are sent to either 241 a reserved, unforwardable, multicast address when using IPv4, or a 242 link-local all-Saratoga-peers multicast address when using IPv6. A 243 BEACON might also be unicast to another known node as a sort of 244 "keepalive". Saratoga nodes may dynamically discover other Saratoga 245 nodes either through listening for BEACONs, through pre- 246 configuration, or via some other trigger from a user, lower-layer 247 protocol, or another process. The BEACON is simply useful in low- 248 delay ad-hoc networking or as explicit confirmation that another node 249 is present; it is not required in order to begin a Saratoga 250 transaction. BEACONs have been used by the DMC satellites to 251 indicate to ground stations that a link has become functional, a 252 solid-state data recorder is online, and the software is ready to 253 transfer any requested files. 255 A Saratoga transaction begins with either a _get_, _put_, _getdir_, 256 or _delete_ transaction REQUEST packet corresponding to a desired 257 download, upload, directory listing, or deletion operation. The most 258 common envisioned transaction is the _get_, which begins with a 259 single Saratoga REQUEST packet sent from the peer wishing to receive 260 the file, to the peer who currently has the file. If the transaction 261 is rejected, then a brief METADATA packet that conveys rejection is 262 generated. If the file-serving peer accepts the transaction, it 263 generates and sends a more useful descriptive METADATA packet, 264 followed by some number of DATA packets constituting the requested 265 file. 267 These DATA packets are finished by (and can intermittently include) a 268 DATA packet with a flag bit set that demands the file-receiver send a 269 reception report in the form of a HOLESTOFILL packet. The 270 HOLESTOFILL packet is a Selective Negative Acknowledgement listing 271 spans of octets within the file that have not yet been received, as 272 well as whether or not the METADATA packet was received. From this 273 HOLESTOFILL packet, the file-sender begins a cycle of selective 274 retransmissions of DATA packets, until it sees a HOLESTOFILL packet 275 that acknowledges total reception of all file data. 277 In the example scenario in Figure 1, a _get_ request is granted. The 278 reliable file delivery experiences loss of a single DATA packet due 279 to channel-induced errors. 281 File-Receiver File-Sender 283 REQUEST ---------------------> 284 (transfer accepted) <--------- METADATA 285 HOLESTOFILL -----------------> (voluntarily sent at start) 286 <------------------------- DATA #1 287 (lost) <------ DATA #2 288 <------------------------- DATA #3 (bit set 289 requesting HOLESTOFILL) 290 HOLESTOFILL -----------------> 291 (indicating that range in DATA #2 was lost) 292 <------------------------- DATA #2 (bit set 293 requesting HOLESTOFILL) 294 HOLESTOFILL -----------------> 295 (complete file and METADATA received) 297 Figure 1: Example _get_ transaction sequence 299 A _getdir_ request proceeds similarly, though the DATA packets 300 contain the contents of a directory listing, described later, rather 301 than a given file's bytes. _getdir_ is the only request to apply to 302 directories. 304 The HOLESTOFILL and DATA packets are allowed to be sent at any time 305 within the scope of a transaction in order for the file-sending node 306 to optimize buffer management and transmission order. For example, 307 if the file-receiver already has the first half of a file from a 308 previous disrupted transfer, it may send a HOLESTOFILL at the 309 beginning of the transaction indicating that it has the first half of 310 the file, and so only needs the last half of the file. Thus, 311 efficient recovery from interrupted sessions between peers becomes 312 possible, similar to ranged FTP and HTTP requests. 314 In deep-space scenarios, the large propagation delays and round-trip 315 times involved prohibit ping-pong packet exchanges (such as TCP's 316 SYN/ACK) for starting transactions. The Saratoga _put_ transaction 317 is useful in such cases. A _put_ is initiated by the file-sender 318 sending a METADATA packet followed by immediate DATA packets. This 319 is highly desirable in long-propagation deep-space (and similar) 320 scenarios, without first waiting for a HOLESTOFILL. This can be 321 considered an "optimistic" mode of protocol operation, as it assumes 322 the transaction request will be granted. If the sender of a PUT 323 request sees a METADATA packet indicating that the request was 324 declined, it MUST stop sending any DATA packets within that 325 transaction immediately. Since this type of _put_ is open-loop for 326 some period of time, it should not be used in scenarios where 327 congestion is a valid concern; in these cases, the file-sender should 328 wait on its METADATA to be acknowledged by a HOLESTOFILL before 329 sending DATA packets within the transaction. 331 Figure 2 illustrates the sequence of packets in an example _put_ 332 transaction where the second DATA packet is lost. Other than the way 333 that it is initiated, a _put_ transaction is identical to a _get_ 334 transaction. 336 File-Sender File-Receiver 338 METADATA ----------------> 339 (transfer accepted) <---------- HOLESTOFILL 340 DATA #1 ----------------> 341 DATA #2 ---> (lost) 342 DATA #3 (bit set ------------> 343 requesting HOLESTOFILL) 344 (DATA #2 lost) <------------- HOLESTOFILL 345 DATA #2 (bit set -----------> 346 requesting HOLESTOFILL) 347 (transfer complete) <---------- HOLESTOFILL 349 Figure 2: Example PUT transaction sequence 351 The _delete_ transactions are simple single packet requests that 352 trigger a HOLESTOFILL packet with a status code that indicates 353 whether the file was deleted or not. If the file is not able to be 354 deleted for some reason, this reason can be conveyed in the Status 355 field of the HOLESTOFILL packet. 357 A _get_ REQUEST packet that does not specify a filename (i.e. the 358 request contains a zero-length File Path field) is specially defined 359 to be a request for any chosen file that the peer wishes to send it. 360 This allows a Saratoga peer to blindly request any files that the 361 other Saratoga peer has ready for it, without prior knowledge of the 362 directory listing, and without requiring the ability to examine files 363 or decode remote file names/paths for meaningful information such as 364 final destination. 366 If a file is larger than Saratoga can be expected to transfer during 367 a time-limited contact, there are at least two feasible options: 369 (1) The application can use proactive fragmentation to create 370 multiple smaller-sized files. Saratoga can transfer some number of 371 these smaller files fully during a contact. 373 (2) To avoid file fragmentation, a Saratoga file-receiver can retain 374 a partially-transferred file and request transfer of the unreceived 375 bytes during a later contact. This uses a HOLESTOFILL packet to make 376 clear how much of the file has been successfully received and where 377 transfer should be resumed from. On resumption, the new METADATA 378 (including file length, file timestamps, and possibly MD5 sum) MUST 379 match that of the previous METADATA in order to re-establish the 380 transfer. Otherwise, the file-receiver MUST assume that the file has 381 changed and purge the DATA received during the first contact. 383 If a file contains separate parts that require reliable transmission 384 without errors or that can tolerate errors in delivered content, 385 proactive fragmentation can be used to split the file into separate 386 reliable and unreliable files that can be transferred separately, 387 using UDP or UDP-Lite. 389 If parts of a file require reliability but the rest can be sent by 390 unreliable transfer, the file-sender can use its knowledge of the 391 internal file structure and vary DATA packet size so that the 392 reliable parts always start after the offset field and are covered by 393 the UDP-Lite checksum. 395 A file that permits unreliable delivery may be transferred onwards 396 using UDP, although the METADATA flag indicating that unreliable 397 transmission is permitted is retained for later hops, which may 398 revert to using UDP-Lite. If the current sender does not understand 399 the internal file format to be able to decide what parts must be 400 protected, the current sender or receiver does not support UDP-Lite, 401 or the current protocol stack only implements error-free frame 402 delivery below the UDP layer, then the file may be delivered using 403 UDP. 405 Like the BEACON packets, a _put_ or a response to a _get_ may be sent 406 to the dedicated IPv4 Saratoga multicast address (allocated to 407 224.0.0.108) or the dedicated IPv6 link-local multicast address 408 (allocated to FF02:0:0:0:0:0:0:6C) for multiple file-receivers on the 409 link to hear. This is at the discretion of the file-sender, if it 410 believes that there is interest from multiple receivers. In-progress 411 DATA transfers may also be moved seamlessly from unicast to multicast 412 if the file-sender learns during a transfer, from receipt of further 413 unicast _get_ REQUEST packets, that multiple nodes are interested in 414 the file. The associated METADATA packet is multicast when this 415 transition takes place, and is then repeated periodically while the 416 DATA stream is being sent, to inform newly-arrived listeners about 417 the file being multicast. Acknowledgements MUST NOT be demanded by 418 multicast DATA packets, to prevent ack implosion at the file-sender, 419 and instead holestofill information is aggregated and sent 420 voluntarily by all file-receivers. File-receivers respond to 421 multicast DATA with multicast HOLESTOFILL packets. File-receivers 422 should introduce a short random delay before sending a multicast 423 HOLESTOFILL packet, to prevent ack implosion after a channel-induced 424 loss, and must listen for HOLESTOFILL packets from others, to avoid 425 duplicating fill requests. The file-sender SHOULD repeat any initial 426 unicast portion of the transfer as multicast last of all, and may 427 repeat and cycle through multicast of the file several times while 428 file-receivers express interest via HOLESTOFILL or _get_ packets. 429 Once in multicast and with METADATA being repeated periodically, new 430 file-receivers do not need to send individual REQUEST packets. If a 431 transfer has been started using UDP-Lite and new receivers indicate 432 UDP-only capability, multicast transfers MUST switch to using UDP to 433 accommodate them. 435 3. Optional Parts of Saratoga 437 Implementing support for some parts of Saratoga is optional. These 438 parts are: 440 - sending and parsing BEACONs 442 - support for working with DTN bundles and a bundle agent as an 443 application driving Saratoga. Use of a filesystem is expected. 445 - transfers permitting some errors in content delivered, using UDP- 446 Lite. These can be useful for decreasing delivery time over 447 unreliable channels, especially for unidirectional links, and in 448 decreasing computational overheard for the UDP Lite checksum - but 449 requires that lower-layer frames permit delivery of unreliable data 450 to be really useful. 452 - streaming data, including real-time streaming of content of unknown 453 length. This streaming can be unreliable (without resend requests) 454 or reliable (with resend requests). Session protocols such as http 455 expect reliable streaming, and can be used in delay-tolerant networks 456 [I-D.wood-dtnrg-http-dtn-delivery]. Although Saratoga data delivery 457 is inherently one-way, where a stream of DATA packets elicits a 458 stream of HOLESTOFILL packets, bidirectional duplex communication can 459 be established by using two Saratoga transfers flowing in opposite 460 directions. 462 - sending and responding to packet timestamps in DATA and HOLESTOFILL 463 packets. These timestamps are useful for streaming and for giving a 464 file-sender an indication of path latency for rate control. There is 465 no need for a file-receiver to understand the format used for these 466 timestamps for it to be able to receive and reflect them. 468 - performing congestion control at the sender, based on feedback from 469 acknowledgement HOLESTOFILL packets, or requiring simple open-loop 470 rate control to only use a fixed amount of link capacity. 472 - multicast DATA transfers, if judged useful for the environment in 473 which Saratoga is deployed. 475 4. Packet Types 477 Saratoga is defined for use with UDP over either IPv4 or IPv6 478 [RFC0768]. UDP checksums, which are mandatory with IPv6, MUST be 479 used with IPv4. Within either version of IP datagram, a Saratoga 480 packet appears as a typical UDP header followed by an octet 481 indicating how the remainder of the packet is to be interpreted: 483 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 484 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 485 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 486 | UDP source port | UDP destination port | 487 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 488 | UDP length | UDP checksum | 489 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 490 |Ver|Packet Type| other Saratoga fields ... // 491 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 493 Saratoga data transfers can also be carried out using UDP-Lite 494 [RFC3828]. If Saratoga can be carried over UDP-Lite, the 495 implementation MUST also support UDP. All packet types except DATA 496 MUST be sent using UDP with checksums turned on. For reliable 497 transfers, DATA packets are sent using UDP with checksums turned on. 498 For files where unreliable transfer has been indicated as desired and 499 possible, the sender MAY send DATA packets unreliably over UDP-Lite, 500 where UDP-Lite protects only the Saratoga headers and parts of the 501 file that must be transmitted reliably. 503 The two-bit Saratoga version field ("Ver") identifies the version of 504 the Saratoga protocol that the packet conforms to. The value 01 505 should be used in this field for implementations conforming to the 506 specification in this document, which specifies version 1 of 507 Saratoga. The value 00 was used in earlier implementations, prior to 508 the formal specification and public submission of the protocol 509 design, and is incompatible with version 01 in several respects. 511 The six-bit Saratoga "Packet Type" field indicates how the remainder 512 of the packet is intended to be decoded and processed: 514 +---+-------------+-------------------------------------------+ 515 | # | Type | Use | 516 +---+-------------+-------------------------------------------+ 517 | 0 | BEACON | Beacon packet indicating peer status | 518 | 1 | REQUEST | Commands peer to start a transfer | 519 | 2 | METADATA | Carries file transfer metadata | 520 | 3 | DATA | Carries octets of file data | 521 | 4 | HOLESTOFILL | Signals list of unreceived data to sender | 522 +---+-------------+-------------------------------------------+ 524 Several of these packet types include a Flags field, for which only 525 some of the bits have defined meanings and usages in this document. 526 Other, undefined, bits may be reserved for future use. Following the 527 principle of being conservative in what you send and liberal in what 528 you accept, a packet sender MUST set any undefined bits to zero, and 529 a packet recipient MUST NOT rely on these undefined bits being zero 530 on reception. 532 The specific formats for the different types of packets are given in 533 this section. Some packet types contain file offset descriptor 534 fields, which contain unsigned integers. The lengths of the offset 535 descriptors are fixed within a transfer, but vary between file 536 transfers. The size is set for each particular transfer, depending 537 on the choice of offset descriptor width made in the METADATA packet, 538 which in turn depends on the size of file being transferred. 540 In this document, all of the packet structure figures illustrating a 541 packet format assume 32-bit lengths for these offset descriptor 542 fields, and indicate the transfer-dependent length of the fields by 543 using a "(descriptor)" designation within the [field] in all packet 544 diagrams. That is: 546 The example 32-bit descriptors shown in all diagrams here 548 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 549 [ (descriptor) ] 550 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 552 are suitable for files of up to 4GiB - 1 octets in length, and may be 553 replaced in a file transfer by descriptors using a different length, 554 depending on the size of file to be transferred: 556 128-bit descriptor for very long files (optional) 558 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 559 [ (descriptor) / 560 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 561 / (descriptor, continued) / 562 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 563 / (descriptor, continued) / 564 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 565 / (descriptor, continued) ] 566 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 568 64-bit descriptor for longer files (optional) 570 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 571 [ (descriptor) / 572 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 573 / (descriptor, continued) ] 574 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 576 16-bit descriptor for short files (MUST be supported) 578 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 579 [ (descriptor) ] 580 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 582 For offset descriptors and types of content being transferred, the 583 related flag bits in BEACON and REQUEST indicate capabilities, while 584 in METADATA and DATA those flag bits are used slightly differently, 585 to indicate the content being transferred. 587 Saratoga packets are intended to fit within link MTUs to avoid the 588 inefficiencies and overheads of lower-layer fragmentation. A 589 Saratoga implementation itself does not perform any form of MTU 590 discovery, but is assumed to be configured with knowledge of usable 591 maximum IP MTUs for the link interfaces it uses. 593 4.1. BEACON 595 BEACON packets may be multicast periodically by nodes willing to act 596 as Saratoga peers. Some implementations have done so every 100 597 milliseconds, but this rate is arbitrary, and should be chosen to be 598 appropriate for the environment and implementation. 600 The main purpose for sending BEACONs is to announce the presence of 601 the node to potential peers (e.g. satellites, ground stations) to 602 provide automatic service discovery, and also to confirm the activity 603 or presence of the peer. 605 The Endpoint Identifier (EID) in the BEACON serves to uniquely 606 identify the Saratoga peer. Whenever the Saratoga peer begins using 607 a new IP address, it SHOULD issue a BEACON on it and repeat the 608 BEACON periodically, to enable listeners to associate the IP address 609 with the EID and the peer. 611 Format 613 0 1 2 3 614 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 615 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 616 |0 1| Type | Flags | 617 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 618 | Endpoint identifier... // 619 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+// 621 where 623 +------------+------------------------------------------------------+ 624 | Field | Description | 625 +------------+------------------------------------------------------+ 626 | Type | 0 | 627 | Flags | convey whether or not the peer is ready to | 628 | | send/receive and what the maximum supported file | 629 | | size range and descriptor is. | 630 | Endpoint | This can be used to uniquely identify the sending | 631 | identifier | Saratoga peer, or the administrative node that the | 632 | | BEACON-sender is associated with. If Saratoga is | 633 | | being used with a bundle agent, a bundle endpoint ID | 634 | | (EID) can be used here. | 635 +------------+------------------------------------------------------+ 637 The Flags field is used to provide some additional information about 638 the peer. The first octet of the Flags field is currently in use. 639 The later two octets are for future use, and MUST be set to zero. 641 The two highest-order bits (bits 8 and 9 above) indicate the maximum 642 supported file size parameters that the peer's Saratoga 643 implementation permits. Other Saratoga packet types contain 644 variable-length fields that convey file sizes or offsets into a file 645 -- the file offset descriptors. These descriptors may be 16-bit, 32- 646 bit, 64-bit, or 128-bit in length, depending on the size of the file 647 being transferred and/or the integer types supported by the sending 648 peer. The indicated bounds for the possible values of these bits are 649 summarized below: 651 +-------+-------+-------------------------+-------------------+ 652 | Bit 8 | Bit 9 | Supported Field Sizes | Maximum File Size | 653 +-------+-------+-------------------------+-------------------+ 654 | 0 | 0 | 16 bits | 2^16 - 1 octets. | 655 | 0 | 1 | 16 or 32 bits | 2^32 - 1 octets. | 656 | 1 | 0 | 16, 32, or 64 bits | 2^64 - 1 octets. | 657 | 1 | 1 | 16, 32, 64, or 128 bits | 2^128 - 1 octets. | 658 +-------+-------+-------------------------+-------------------+ 660 If a Saratoga peer advertises it is capable of receiving a certain 661 size of file, then it MUST also be capable of receiving files sent 662 using smaller descriptor values. This avoids overhead on small 663 files, while increasing interoperability between peers. 665 It is likely when sending unbounded streams that a larger offset 666 descriptor field size will be preferred to minimise problems with 667 offset sequences wrapping. Protecting against sequence wrapping is 668 discussed in the HOLESTOFILL section. 670 +-----+-------+-----------------------------------------------------+ 671 | Bit | Value | Meaning | 672 +-----+-------+-----------------------------------------------------+ 673 | 10 | 0 | not able to pass bundles to a local bundle agent; | 674 | | | handles files. | 675 | 10 | 1 | can pass marked bundles to a local bundle agent. | 676 +-----+-------+-----------------------------------------------------+ 678 Bit 10 is reserved for DTN bundle agent use, indicating whether the 679 sender is capable of handling bundles via a local bundle agent. This 680 is described in [I-D.wood-dtnrg-saratoga]. 682 Any type of host identifier can be used in the endpoint identifier 683 field, as long as it is a reasonably unique string within the range 684 of operational deployment. This field encompasses the remainder of 685 the packet, and might contain non-UTF-8 and/or null characters. 687 +-----+-------+--------------------------------------+ 688 | Bit | Value | Meaning | 689 +-----+-------+--------------------------------------+ 690 | 11 | 0 | not capable of supporting streaming. | 691 | 11 | 1 | capable of supporting streaming. | 692 +-----+-------+--------------------------------------+ 694 Bit 11 is used to indicate whether the sender is capable of sending 695 and receiving continuous streams. 697 +--------+--------+------------------------------------------------+ 698 | Bit 12 | Bit 13 | Capability and willingness to send files | 699 +--------+--------+------------------------------------------------+ 700 | 0 | 0 | cannot send files at all. | 701 | 0 | 1 | invalid. | 702 | 1 | 0 | capable of sending, but not willing right now. | 703 | 1 | 1 | capable of and willing to send files. | 704 +--------+--------+------------------------------------------------+ 706 +--------+--------+-------------------------------------------------+ 707 | Bit 14 | Bit 15 | Capability and willingness to receive files | 708 +--------+--------+-------------------------------------------------+ 709 | 0 | 0 | cannot receive files at all. | 710 | 0 | 1 | invalid. | 711 | 1 | 0 | capable of receiving, but will reject METADATA. | 712 | 1 | 1 | capable of and willing to receive files. | 713 +--------+--------+-------------------------------------------------+ 715 Also in the Flags field, bits 12 and 14 act as capability bits, while 716 bits 13 and 15 augment those flags with bits indicating current 717 willingness to use the capability. 719 Bits 12 and 13 deal with sending, while bits 14 and 15 deal with 720 receiving. If bit 12 is set, then the peer has the capability to 721 send files. If bit 14 is set, then the peer has the capability to 722 receive files. Bits 13 and 15 indicate willingness to send and 723 receive files, respectively. 725 A peer that is able to act as a file-sender MUST set the capability 726 bit 12 in all BEACONs that it sends, regardless of whether it is 727 willing to send any particular files to a particular peer at a 728 particular time. Bit 13 indicates the current presence of data to 729 send and a willingness to send it in general, in order to augment the 730 capability advertised by bit 12. 732 If bit 14 is set, then the peer is capable of acting as a receiver, 733 although it still might not currently be ready or willing to receive 734 files (for instance, it may be low on free storage). This bit MUST 735 be set in any BEACON packets sent by nodes capable of acting as file- 736 receivers. Bit 15 augments this by expresses a current general 737 willingness to receive and accept files. 739 +-----+-------+-----------------------------------------------------+ 740 | Bit | Value | Meaning | 741 +-----+-------+-----------------------------------------------------+ 742 | 16 | 0 | supports DATA transfers over UDP only. | 743 | 16 | 1 | supports DATA transfers over both UDP and UDP-Lite. | 744 +-----+-------+-----------------------------------------------------+ 745 Bit 16 is used to indicate whether the sender is capable of sending 746 and receiving unreliable transfers via UDP-Lite. 748 4.2. REQUEST 750 A REQUEST packet is a command to perform either a _get_, _getdir_, or 751 _delete_ transaction. 753 Format 755 0 1 2 3 756 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 757 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 758 |0 1| Type | Flags | 759 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 760 | Id | 761 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 762 | variable-length File Path ... / 763 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 764 / / 765 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 766 / | null byte | / 767 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 768 / variable-length Authentication Field (optional) | 769 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 771 where 773 +--------+----------------------------------------------------------+ 774 | Field | Description | 775 +--------+----------------------------------------------------------+ 776 | Type | 1 | 777 | Flags | provide additional information about the requested | 778 | | file/operation; see table below for definition. | 779 | Id | uniquely identifies the transaction between two peers. | 780 | File | the path of the requested file/directory following the | 781 | Path | rules described below. | 782 +--------+----------------------------------------------------------+ 784 The Id that is used during transactions serves to uniquely associate 785 a given packet with a particular transaction. This enables multiple 786 simultaneous data transfer transactions between two peers, with each 787 peer deciding how to multiplex and prioritise the parallel flows it 788 sends. The Id for a transaction is selected by the initiator so as 789 to not conflict with any other in-progress or recent transactions 790 with the same host. This Id should be unique and generated using 791 properties of the file, which will remain constant across a host 792 reboot. The 3-tuple of both host identifiers and a carefully- 793 generated transaction Id field can be used to uniquely index a 794 particular transaction's state. 796 In the Flags field, the bits labelled 8 and 9 in the figure above 797 indicate the maximum supported file length fields that the peer can 798 handle, and are interpreted exactly as the bits 8 and 9 in the BEACON 799 packet described above. The remaining defined bits are: 801 +-----+-------+-----------------------------------------------------+ 802 | Bit | Value | Meaning | 803 +-----+-------+-----------------------------------------------------+ 804 | 10 | 0 | The requester cannot handle bundles locally. | 805 | 10 | 1 | The requester can handle bundles. | 806 | 11 | 0 | The requester cannot receive streams. | 807 | 11 | 1 | The requester is also able to receive streams. | 808 | 14 | 0 | a _get_ or _getdir_ transaction is requested | 809 | 14 | 1 | a _delete_ transaction is requested | 810 | 15 | 0 | the File Path field holds a file for a _get_ or | 811 | | | _delete_ | 812 | 15 | 1 | the File Path field specifies a directory name for | 813 | | | a _getdir_ or _delete_ | 814 | 16 | 0 | The requester is able to receive DATA over UDP | 815 | | | only. | 816 | 16 | 1 | The requester is also able to receive DATA over | 817 | | | UDP-Lite. | 818 +-----+-------+-----------------------------------------------------+ 820 The File Path portion of a _get_ packet is a null-terminated UTF-8 821 encoded string [RFC3629] that represents the path and base file name 822 on the file-sender of the file (or directory) that the file-receiver 823 wishes to perform the _get_, _getdir_, or _delete_ operation on. 824 Implementations SHOULD only send as many octets of File Path as are 825 needed for carrying this string, although some implementations MAY 826 choose to send a fixed-size File Path field in all REQUEST packets 827 that is filled with null octets after the last UTF-8 encoded octet of 828 the path. A maximum of 1024 octets for this field, and for the File 829 Path fields in other Saratoga packet types, is used to limit the 830 total packet size to within a single IPv6 minimum MTU (minus some 831 padding for network layer headers), and thus avoid the need for 832 fragmentation. The 1024-octet maximum applies after UTF-8 encoding 833 and null termination. 835 As in the standard Internet File Transfer Protocol (FTP) [RFC0959], 836 for path separators, Saratoga allows the local naming convention on 837 the peers to be used. There are security implications to processing 838 these strings without some intelligent filtering and checking on the 839 filesystem items they refer to, as discussed in the Security 840 Considerations section later within this document. 842 If the File Path field is empty, i.e. is a null-terminated zero- 843 length string one octet long, then this indicates that the file- 844 receiver is ready to receive any file that the file-sender would like 845 to send it, rather than requesting a particular file. This allows 846 the file-sender to determine the order and selection of files that it 847 would like to forward to the receiver in more of a "push" manner. Of 848 course, file retrieval could also follow a "pull" manner, with the 849 file-receiving host requesting specific files from the file-sender. 850 This may be desirable at times if the file-receiver is low on storage 851 space, or other resources. The file-receiver could also use the 852 Saratoga _getdir_ transaction results in order to select small files, 853 or make other optimizations, such as using its local knowledge of 854 contact times to pick files of a size likely to be able to be 855 delivered completely. File transfer through pushing sender-selected 856 files implements delivery prioritization decisions made solely at the 857 Saratoga file-sending node. File transfer through pulling specific 858 receiver-selected files implements prioritization involving more 859 participation from the Saratoga file-receiver. This is how Saratoga 860 implements Quality of Service (QoS). 862 The null-terminated File Path string MAY be followed by an optional 863 Authentication Field that can be used to validate the REQUEST packet. 864 Any value in the Authentication Field is the result of a computation 865 of packet contents that SHOULD include, at a minimum, source and 866 destination IP addresses and port numbers and packet length in a 867 'pseudo-header', as well as the content of all Saratoga fields from 868 Version to File Path, excluding the predictable null-termination 869 octet. This Authentication Field can be used to allow the REQUEST 870 receiver to discriminate between other peers, and permit and deny 871 various REQUEST actions as appropriate. The format of this field is 872 unspecified for local use. 874 REQUEST packets may be sent multicast, to learn about all listening 875 nodes. A multicast _get_ request for a file that elicits multiple 876 METADATA responses should be followed by unicast HOLESTOFILL packets 877 with status errors cancelling all but one of the proposed transfers. 878 File timestamps in the Directory Entry can be used to select the most 879 recent version of an offered file, and the host to fetch it from. 881 If the receiver already has the file at the expected file path and is 882 requesting an update to that file, REQUEST can be sent after a 883 METADATA advertising that file, to allow the sender to determine 884 whether a replacement for the file should be sent. 886 Delete requests are ignored for files currently being transferred. 888 4.3. METADATA 890 METADATA packets are sent as part of a data transfer transaction 891 (_get_, _getfile_, and _put_). A METADATA packet says how large the 892 file is and what its name is, as well as what size of file offset 893 descriptor is chosen for the session. METADATA packets are normally 894 sent at the start of a data transfer, but may be repeated if 895 requested. 897 Format 899 0 1 2 3 900 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 901 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 902 |0 1| Type | Flags |Sumtype| 903 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 904 | Id | 905 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 906 | / 907 / / 908 / example error-detection checksum (128-bit MD5 shown) / 909 / / 910 / | 911 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 912 | / 913 / single Directory Entry describing file / 914 / (variable length) / 915 / // 916 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 918 where 920 +-----------+-------------------------------------------------------+ 921 | Field | Description | 922 +-----------+-------------------------------------------------------+ 923 | Type | 2 | 924 | Flags | indicate additional boolean metadata about a file | 925 | Sumtype | indicates whether a checksum is present after the Id, | 926 | | and what type it is. | 927 | Id | identifies the transaction that this packet describes | 928 | Checksum | an example included checksum covering file contents | 929 | Directory | describes file system information about the file, | 930 | Entry | including file length, file timestamps, etc.; the | 931 | | format is specified in Section 5 | 932 +-----------+-------------------------------------------------------+ 934 The first octet of the Flags field is currently specified for use. 935 The later two octets are reserved for future use, and MUST be set to 936 zero. 938 In the Flags field, the bits labelled 8 and 9 in the figure above 939 indicate the exact size of the offset descriptor fields used in this 940 particular packet and are interpreted exactly as the bits 8 and 9 in 941 the BEACON packet described above. The value of these bits 942 determines the size of the File Length field in the current packet, 943 as well as indicating the size of the offset fields used in DATA and 944 HOLESTOFILL packets within the session that will follow this packet. 946 +--------+--------+-------------------------------------------------+ 947 | Bit 10 | Bit 11 | Type of transfer | 948 +--------+--------+-------------------------------------------------+ 949 | 0 | 0 | a file is being sent. | 950 | 0 | 1 | the file being sent should be interpreted as a | 951 | | | directory record. | 952 | 1 | 0 | a bundle is being sent. | 953 | 1 | 1 | an indefinite-length stream is being sent. | 954 +--------+--------+-------------------------------------------------+ 956 Also inside the Flags field, bits 10 and 11 indicate what is being 957 transferred - a file, special file that contains directory records, 958 bundle, or stream. The value 01 indicates that the METADATA and DATA 959 packets are being generated in response to a _getdir_ REQUEST, and 960 that the assembled DATA contents should be interpreted as a sequence 961 of Directory Records, as defined in Section 5. 963 +-----+-------+-----------------------------------------------------+ 964 | Bit | Value | Meaning | 965 +-----+-------+-----------------------------------------------------+ 966 | 12 | 0 | This transfer is in progress. | 967 | 12 | 1 | This transfer is no longer in progress, and has | 968 | | | been terminated. | 969 +-----+-------+-----------------------------------------------------+ 971 Bit 12 indicates whether the transfer is in progress, or has been 972 terminated by the sender. It is normally set to 1 only when METADATA 973 is resent to indicate that a stream transfer has been ended. 975 +--------+----------------------------------------------------------+ 976 | Bit 13 | Use | 977 +--------+----------------------------------------------------------+ 978 | 0 | This file's content MUST be delivered reliably without | 979 | | errors using UDP. | 980 | 1 | This file's content MAY be delivered unreliably, without | 981 | | errors, or partly unreliably, where errors are | 982 | | tolerated, using UDP-Lite. | 983 +--------+----------------------------------------------------------+ 984 Bit 13 indicates whether the file must be sent reliably or can be 985 sent at least partly unreliably, using UDP-Lite. This flag can only 986 be set if the originator of the file knows that at least some of the 987 file content is suitable for sending unreliably and is robust to 988 errors. This flag reflects a property of the file itself. This flag 989 may still be set if the immediate file-receiver is only capable of 990 UDP delivery, on the assumption that this preference will be 991 preserved for later transfers where UDP-Lite transfers may be taken 992 advantage of by senders with knowledge of the internal file 993 structure. The file-sender may know that the receiver is capable of 994 handling UDP-Lite, either from a _get_ REQUEST, from exchange of 995 BEACONs, or a-priori. 997 The high four bits of the Flags field, bits 28-31, are used to 998 indicate if an error-detection checksum has been included in the 999 METADATA for the file to be transferred. Here, bits 0000 indicate 1000 that no checksum is present, with the implicit assumption that the 1001 application will do its own end-to-end check. Other values indicate 1002 the type of checksum to use. The choice of checksum depends on the 1003 available computing power and the length of the file to be 1004 checksummed. Longer files require stronger checksums to ensure 1005 error-free delivery. The checksum of the file to be transferred is 1006 carried as shown, with a fixed-length field before the varying-length 1007 File Length and File Name information fields. 1009 Assigned values for the checksum field are: 1011 +-----------+-------------------------------------------------------+ 1012 | Value | Use | 1013 | (0-15) | | 1014 +-----------+-------------------------------------------------------+ 1015 | 0 | No checksum is provided. | 1016 | 1 | 32-bit CRC32 checksum, suitable for small files. | 1017 | 2 | 128-bit MD5 checksum, suitable for larger files | 1018 | 3 | 160-bit SHA-1 checksum, suitable for larger files but | 1019 | | slower to process than MD5. | 1020 +-----------+-------------------------------------------------------+ 1022 It is expected that higher values will be allocated to new and 1023 stronger checksums able to better protect larger files. A checksum 1024 SHOULD be included for files being transferred. The checksum SHOULD 1025 be as strong as possible. Streaming of an indefinite-length stream 1026 MUST set the checksum field to zero. 1028 It is expected that a minimum of the MD5 checksum will be used, 1029 unless the Saratoga implementation is used exclusively for small 1030 transfers at the low end of the 16-bit file descriptor range, such as 1031 on low-performing hardware, where the weaker CRC-32c checksum can 1032 suffice. 1034 The CRC32 checksum is computed as described for the CRC-32c algorithm 1035 given in [RFC3309]. 1037 The MD5 Sum field is generated via the MD5 algorithm [RFC1321], 1038 computed over the entire contents of the file being transferred. The 1039 file-receiver can compute the MD5 result over the reassembled 1040 Saratoga DATA packet contents, and compare this to the METADATA's MD5 1041 Sum field in order to gain confidence that there were no undetected 1042 protocol errors or UDP checksum weaknesses encountered during the 1043 transfer. Although MD5 is known to be less than optimal for security 1044 uses, it remains excellent for non-security use in error detection 1045 (as is done here in Saratoga), and has better performance 1046 implications than cryptographically-stronger alternatives given the 1047 limited available processing of many DTN use cases. 1049 Checksums may be privately keyed for local use, to allow transmission 1050 of authenticated or encrypted files delivered in DATA packets. This 1051 has limitations, discussed further in the Security Considerations 1052 section at end. 1054 Use of the checksum to ensure that a file has been correctly relayed 1055 to the receiving node is important. A provided checksum MUST be 1056 checked against the received data file. If checksum verification 1057 fails, either due to corruption or due to the receiving node not 1058 having the right key for a keyed checksum), the file MUST be 1059 discarded. If the file is to be relayed onwards later to another 1060 Saratoga peer, the metadata, including the checksum, MUST be retained 1061 with the file and SHOULD be retransmitted onwards unchanged with the 1062 file for end-to-end coverage. If it is necessary to recompute the 1063 checksum or encrypted data for the new peer, either because a 1064 different key is in use or the existing checksum algorithm is not 1065 supported, the new checksum MUST be computed before the old checksum 1066 is verified, to ensure overlapping checksum coverage and detect 1067 errors introduced in file storage. 1069 If the METADATA is in response to a _get_ REQUEST including a file 1070 record, and the record information for the held file matches what the 1071 requester already has, as has been indicated by a previously-received 1072 METADATA advertisement from the requester, then only the METADATA is 1073 sent repeating this information and verifying that the file is up to 1074 date. If the record information does not match and a newer file can 1075 be supplied, the METADATA begins a transfer with following DATA 1076 packets to update the file. 1078 4.4. DATA 1080 A series of DATA packets form the main part of a data transfer 1081 transaction (_get_, _put_, or _getdir_). The payloads constitute the 1082 actual file data being transferred. 1084 Format 1086 0 1 2 3 1087 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1088 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1089 |0 1| Type | Flags | 1090 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1091 | Id | 1092 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1093 | / 1094 / Timestamp/nonce information (optional) / 1095 / / 1096 / | 1097 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1098 [ Offset (descriptor) ] 1099 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1101 where 1103 +-----------------+-------------------------------------------------+ 1104 | Field | Description | 1105 +-----------------+-------------------------------------------------+ 1106 | Type | 3 | 1107 | Flags 8 and 9 | bit 8 and 9 specify the size of offset | 1108 | | descriptor, as elsewhere. | 1109 | Flag 10 | bit 10, with bit 11, indicates whether a file, | 1110 | | bundle, stream or directory entry is being | 1111 | | carried. This bit will normally be zero for | 1112 | | files. | 1113 | Flag 11 | bit 11 is used with bit 10. Normally this bit | 1114 | | will be zero for files. | 1115 | Flag 12 | bit 12 indicates that an optional timestamp or | 1116 | | nonce is included in the DATA header before the | 1117 | | offset descriptor. | 1118 | Flag 15 | bit 15 requests an immediate HOLESTOFILL ack to | 1119 | | be generated in response to receiving this | 1120 | | packet. | 1121 | Id | identifies the transaction that this packet | 1122 | | belongs to | 1123 | Timestamp/nonce | provides optional timing or identification | 1124 | | information unique to this packet. See | 1125 | | Appendix A for details. | 1126 | Offset | the offset in octets to the location where the | 1127 | | first byte of this packet's payload is to be | 1128 | | written | 1129 +-----------------+-------------------------------------------------+ 1131 The DATA packet has a minimum size of ten octets, using sixteen-bit 1132 descriptors and no timestamps. 1134 DATA packets are normally sent error-free using UDP for reliable 1135 transfer (of both content and delivery). However, for transfers that 1136 can tolerate content errors, DATA packets MAY be sent using UDP-Lite. 1137 If UDP-Lite is used, the file-sender must know that the file-receiver 1138 is capable of handling UDP-Lite, and the file contents to be 1139 transferred should be resilient to errors. The UDP-Lite checksum 1140 MUST protect the Saratoga headers, up to and including the offset 1141 descriptor, and MAY protect more of each packet's payload, depending 1142 on the file-sender's knowledge of the internal structure of the file 1143 and the file's reliability requirements. 1145 Flag bits 8 and 9 are set to indicate the size of the offset 1146 descriptor as described for BEACON and METADATA packets, so that each 1147 DATA packet is self-describing. This allows the DATA packet to be 1148 used to construct a file even when the initial METADATA is lost and 1149 must be resent. The flag values for bits 8, 9, 10 and 11 MUST be the 1150 same as indicated in the initial METADATA packet. 1152 +--------+--------+-------------------------------------------------+ 1153 | Bit 10 | Bit 11 | Type of transfer | 1154 +--------+--------+-------------------------------------------------+ 1155 | 0 | 0 | a file is being sent. | 1156 | 0 | 1 | the file being sent should be interpreted as a | 1157 | | | directory record. | 1158 | 1 | 0 | a bundle is being sent. | 1159 | 1 | 1 | an indefinite-length stream is being sent. | 1160 +--------+--------+-------------------------------------------------+ 1162 Also inside the Flags field, bits 10 and 11 indicate what is being 1163 transferred - a file, special file that contains directory records, 1164 bundle, or stream. The value 01 indicates that the METADATA and DATA 1165 packets are being generated in response to a _getdir_ REQUEST, and 1166 that the assembled DATA contents should be interpreted as a sequence 1167 of Directory Records, as defined in Section 5. 1169 +-----+-------+-----------------------------------------------------+ 1170 | Bit | Value | Meaning | 1171 +-----+-------+-----------------------------------------------------+ 1172 | 12 | 0 | This packet does not include an optional | 1173 | | | timestamp/nonce field. | 1174 | 12 | 1 | This packet includes an optional timestamp/nonce | 1175 | | | field. | 1176 +-----+-------+-----------------------------------------------------+ 1178 Flag bit 12 indicates that an optional timestamp/nonce is carried in 1179 the packet before the offset field. This timestamp/nonce field is 1180 always sixteen bytes long. Timestamps are particularly useful when 1181 streaming. Timestamps are normally only meaningful to the sender, 1182 and the receiver simply echoes the timestamps back as specified for 1183 HOLESTOFILL packets. Timestamps are particularly useful when 1184 streaming. Timestamps are discussed further in Appendix A. 1186 +-----+-------+------------------------------------+ 1187 | Bit | Value | Meaning | 1188 +-----+-------+------------------------------------+ 1189 | 15 | 0 | No response is requested. | 1190 | 15 | 1 | A HOLESTOFILL packet is requested. | 1191 +-----+-------+------------------------------------+ 1193 Within the Flags field, if bit 15 of the packet is set, the file- 1194 receiver is to immediately generate a HOLESTOFILL packet to provide 1195 the file-sender with up-to-date information regarding the status of 1196 the file transfer. This flag is set carefully and rarely. It may be 1197 set periodically, but infrequently. Asymmetric links with 1198 constrained backchannels can only carry a limited amount of 1199 HOLESTOFILL packets before ack congestion becomes a problem. This 1200 flag SHOULD NOT be set if an unreliable stream is being transferred, 1201 or if multicast is in use. This flag SHOULD be set periodically for 1202 reliable file transfers, or reliable streaming. 1204 Immediately following the DATA header is the payload, which consumes 1205 the remainder of the packet and whose length is implicitly defined by 1206 the end of the packet. The payload octets are directly formed from 1207 the continuous octets starting at the specified Offset in the file 1208 being transferred. No special coding is performed. A zero-octet 1209 payload length is allowable. 1211 The length of the Offset fields used within all DATA packets for a 1212 given transaction MUST be consistent with the length indicated by 1213 bits 8 and 9 of the transactions METADATA packet. If the METADATA 1214 packet has not yet been received, a file-receiver SHOULD request it 1215 via a HOLESTOFILL packet, and MAY choose to enqueue received DATA 1216 packets for later processing after the METADATA arrives. 1218 4.5. HOLESTOFILL 1220 The HOLESTOFILL packet type is used for feedback from a Saratoga 1221 file-receiver to a Saratoga file-sender to indicate transaction 1222 progress and request transmission (usually re-transmission) of 1223 specific sets of octets within the current transaction (called 1224 "holes"). This can be used to clean up losses (or indicate no 1225 losses) at the end of, or during, a transaction, or to efficiently 1226 resume a transfer that was interrupted in a previous transaction. 1228 Format 1230 0 1 2 3 1231 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1232 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1233 |1 0| Type | Flags | Status | 1234 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1235 | Id | 1236 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1237 | / 1238 / Timestamp/nonce information (optional) / 1239 / / 1240 / | 1241 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1242 [ Progress Indicator (descriptor) ] 1243 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1244 [ In-Response-To (descriptor) ] 1245 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1246 | (possibly, several Hole fields) / 1247 / ... / 1248 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1250 where 1252 +----------------+--------------------------------------------------+ 1253 | Field | Description | 1254 +----------------+--------------------------------------------------+ 1255 | Type | 4 | 1256 | Flags | are defined below. | 1257 | Id | identifies the transaction that this packet | 1258 | | belongs to. | 1259 | Status | a value of 0x00 indicates the transfer is | 1260 | | sucessfully proceeding. All other values are | 1261 | | errors terminating the transfer, explained | 1262 | | below. | 1263 | Zero-Pad | an octet fixed at 0x00 to allow later fields to | 1264 | | be conveniently aligned for processing. | 1265 | Progress | the offset of the lowest-numbered octet of the | 1266 | Indicator | file not yet received. | 1267 | In-Response-To | This is only present if the timestamp flag is | 1268 | (optional | set. If the HOLESTOFILL packet is voluntary and | 1269 | timestamp) | the voluntary flag is set, this should repeat | 1270 | | the timestamp of the DATA packet containing the | 1271 | | highest offset seen. If the HOLESTOFILL packet | 1272 | | is in response to a mandatory request, this will | 1273 | | repeat the timestamp of the requesting DATA | 1274 | | packet. The file-sender may use these | 1275 | | timestamps to estimate latency. There are | 1276 | | special considerations for streaming, to protect | 1277 | | against the ambiguity of wrapped offset | 1278 | | descriptor sequence numbers, discussed below. | 1279 | In-Response-To | the offset of the highest-numbered octet within | 1280 | (descriptor) | a DATA packet that generated this HOLESTOFILL | 1281 | | packet, or the offset of the highest-numbered | 1282 | | octet seen if this HOLESTOFILL is generated | 1283 | | voluntarily and the voluntary flag is set. | 1284 | Holes | indications of offset ranges of missing data, | 1285 | | defined below. | 1286 +----------------+--------------------------------------------------+ 1288 The HOLESTOFILL packet has a minimum size of twelve octets, using 1289 sixteen-bit descriptors, a progress indicator but no Hole fields, and 1290 no timestamps. 1292 The Id field is needed to associate the packet with the transaction 1293 that it refers to. Using the Id as a key, the receiver of a packet 1294 can determine the lengths of the Progress Indicator, In-Response-To, 1295 and Hole offsets used within the HOLESTOFILL packet, as this file 1296 offset descriptor size was set in the initial METADATA packet that 1297 established the Id and in DATA packets that the file receiver is 1298 responding to. 1300 Flags bits 8 and 9 are set to indicate the size of the offset 1301 descriptor as described for BEACON and METADATA packets, so that each 1302 HOLESTOFILL packet is self-describing. The flag values here MUST be 1303 the same as indicated in the initial METADATA and DATA packets. 1305 Other bits in the Flags field are defined as: 1307 +-----+-------+---------------------------------------------------+ 1308 | Bit | Value | Meaning | 1309 +-----+-------+---------------------------------------------------+ 1310 | 12 | 0 | This packet does not include a timestamp field. | 1311 | 12 | 1 | This packet includes an optional timestamp field. | 1312 +-----+-------+---------------------------------------------------+ 1314 Flag bit 12 indicates that an optional sixteen-byte timestamp/nonce 1315 field is carried in the packet before the Progress Indicator 1316 descriptor, as discussed for the DATA packet format. Timestamps are 1317 discussed further in Appendix A. 1319 +-----+-------+----------------------------------------+ 1320 | Bit | Value | Meaning | 1321 +-----+-------+----------------------------------------+ 1322 | 13 | 0 | file's METADATA has been received. | 1323 | 13 | 1 | file's METADATA has not been received. | 1324 +-----+-------+----------------------------------------+ 1326 If bit 13 of a HOLESTOFILL packet has been set to indicate that the 1327 METADATA has not yet been received, then the METADATA should be 1328 resent. This flag should normally be clear. 1330 +-----+-------+-----------------------------------------------------+ 1331 | Bit | Value | Meaning | 1332 +-----+-------+-----------------------------------------------------+ 1333 | 14 | 0 | this packet contains the complete current set of | 1334 | | | holes at the file-receiver. | 1335 | 14 | 1 | this packet contains incomplete hole-state; holes | 1336 | | | shown in this packet should supplement other | 1337 | | | incomplete hole-state known to the file-sender. | 1338 +-----+-------+-----------------------------------------------------+ 1340 Bit 14 of the HOLESTOFILL packet is only set when there are too many 1341 holes to fit within a single HOLESTOFILL packet due to MTU 1342 limitations. This causes the hole list to be spread out over 1343 multiple HOLESTOFILL packets, each of which conveys distinct sets of 1344 holes. This could occur, for instance, in a large file _put_ 1345 scenario with a long-delay feedback loop and poor physical layer 1346 conditions. These multiple HOLESTOFILL packets will share In- 1347 Response-To information. When losses are light and/or hole reporting 1348 and repair is relatively frequent, all holes should easily fit within 1349 a single HOLESTOFILL packet, and this flag will be clear. Bit 14 1350 should normally be clear. 1352 In some rare cases of high loss, there may be too many holes in the 1353 received data to convey within a single HOLESTOFILL's size, which is 1354 limited by the link MTU size. In this case, multiple HOLESTOFILL 1355 packets may be generated, and Flags bit 14 should be set on each 1356 HOLESTOFILL packet accordingly, to indicate that each packet holds 1357 incomplete results. The complete group of HOLESTOFILL packets, each 1358 containing incomplete information, will share common In-Response-To 1359 information to distinguish them from any earlier groups. 1361 +-----+-------+----------------------------------------------------+ 1362 | Bit | Value | Meaning | 1363 +-----+-------+----------------------------------------------------+ 1364 | 15 | 0 | This HOLESTOFILL was requested by the file-sender. | 1365 | 15 | 1 | This HOLESTOFILL is sent voluntarily. | 1366 +-----+-------+----------------------------------------------------+ 1368 Flag bit 15 indicates whether the HOLESTOFILL is sent voluntarily or 1369 due to a request by the sender. It affects content of the In- 1370 Response-To timestamp and descriptor fields. 1372 In the case of a transfer proceeding normally, immediately following 1373 the HOLESTOFILL packet header shown above, is a set of "Hole" 1374 definitions. Each Hole definition is a pair of unsigned integers. 1375 For a 32-bit offset descriptor, each Hole definition consists of two 1376 four-octet unsigned integers: 1378 Hole Definition Format 1380 0 1 2 3 1381 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1382 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1383 [ offset to start of hole (descriptor) ] 1384 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1385 [ offset to end of hole (descriptor) ] 1386 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1388 The start of the hole means the offset of the first unreceived byte 1389 in that hole. The end of the hole means the last unreceived byte in 1390 that hole. 1392 For 16-bit descriptors, each Hole definition holds two two-octet 1393 unsigned integers, while Hole definitions for 64- and 128-bit 1394 descriptors require two eight- and two sixteen-octet unsigned 1395 integers respectively. 1397 Since each Hole definition takes up eight octets when 32-bit offset 1398 lengths are used, we expect that well over 100 such definitions can 1399 fit in a single HOLESTOFILL packet, given the IPv6 minimum MTU. 1401 A 'voluntary' HOLESTOFILL is sent at the start of each transaction, 1402 once METADATA information has been received. This indicates that the 1403 receiver is ready to receive the file, or indicates an error or 1404 rejection code, described below. A HOLESTOFILL indicating a 1405 successfully established transfer has a Progress Indicator of zero 1406 and an In-Response-To field of zero. 1408 On receiving a HOLESTOFILL packet, the sender SHOULD prioritize 1409 sending the necessary data to fill those holes, in order to advance 1410 the Progress Indicator at the receiver. 1412 A completed transfer is inferred from the reported receiver window 1413 position. In the final HOLESTOFILL packet sent by the receiver once 1414 the file to be transferred has been completely received, bit 14 MUST 1415 be 0 (indicating a complete set of holes in this packet), there MUST 1416 NOT be any holestofill offset pairs indicating holes, the In- 1417 Response-To field points to the last byte of the file, and the 1418 voluntary flag MUST be set. This 'completed' HOLESTOFILL may be 1419 repeated, depending on subsequent sender behaviour, while internal 1420 state about the transfer remains available to the receiver. 1422 In the case of an error causing a transfer to be aborted, the Status 1423 field holds a code that can be used to explain the cause of the error 1424 to the other peer. A zero value indicates that there have been no 1425 significant errors (this is called a "success HOLESTOFILL" within 1426 this document), while any non-zero value means the transaction should 1427 be aborted (this is called a "failure HOLESTOFILL"). 1429 +------------+------------------------------------------------------+ 1430 | Status | Meaning | 1431 | Value | | 1432 +------------+------------------------------------------------------+ 1433 | 0x00 | Success, No Errors. | 1434 | 0x01 | Unspecified Error. | 1435 | 0x02 | Unable to send file due to resource constraints. | 1436 | 0x03 | Unable to receive file due to resource constraints. | 1437 | 0x04 | File not found. | 1438 | 0x05 | Access Denied. | 1439 | 0x06 | Unknown Id field for transaction. | 1440 | 0x07 | Did not delete file. | 1441 | 0x08 | File length is longer than REQUEST indicates support | 1442 | | for. | 1443 | 0x09 | File offset descriptors do not match expected use or | 1444 | | file length. | 1445 | 0x0A | Unsupported packet type received. | 1446 | 0x0B | DATA flag bits describing transfer have changed | 1447 | | unexpectedly. | 1448 | 0x0C | Receiver is no longer interested in receiving this | 1449 | | file. | 1450 | 0x0D | Receiver wants sender to pause its transfer. | 1451 | 0x0E | Receiver wants sender to resume a previously-paused | 1452 | | transfer. | 1453 | 0x0F | File is in use. | 1454 +------------+------------------------------------------------------+ 1456 The recipient of a failure HOLESTOFILL MUST NOT try to process the 1457 Progress Indicator, In-Response-To, or Hole offsets, because, in some 1458 types of error conditions, the packet's sender may not have any way 1459 of setting them to the right length for the transaction. 1461 When sending an indefinite-length stream, the possibility of offset 1462 sequence numbers wrapping back to zero must be considered. This can 1463 be protected against by using large offsets, and by the stream 1464 receiver. The receiver MUST separate out holes before the offset 1465 wraps to zero from holes after the wrap, and send Hole definitions in 1466 different HOLESTOFILL packets, with Flag 14 set to mark them as 1467 incomplete. Any Hole straddling a sequence wrap MUST be broken into 1468 two separate Holes, with the second Hole starting at zero. The 1469 timestamps in HOLESTOFILL packets carrying any pre-wrap holes should 1470 be earlier than the timestamp in later packets, and should repeat the 1471 timestamp of the last DATA packet seen for that offset sequence 1472 before the following wrap to zero occurred. Receivers indicate that 1473 they no longer wish to receive streams by sending Status Code 0x0C. 1475 5. The Directory Entry 1477 Directory Entries have two uses within Saratoga: 1479 1. Within a METADATA packet, a Directory Entry is used to give 1480 information about the file being transferred, in order to 1481 facilitate proper reassembly of the file and to help the file- 1482 receiver understand how recently the file may have been created 1483 or modified. 1485 2. When a peer requests a directory listing via a _getdir_ REQUEST, 1486 the other peer generates a file containing a series of one or 1487 more concatenated Directory Entry records, and transfers this 1488 file as it would transfer the response to a normal _get_ REQUEST, 1489 sending the records together within DATA packets. This file may 1490 be either temporary or within-memory and not actually a part of 1491 the host's file system itself. 1493 Directory Entry Format 1495 0 1 2 3 1496 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 1497 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1498 [ Size (descriptor) ] 1499 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1500 | Mtime | 1501 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1502 | Ctime | 1503 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1504 | Properties | / 1505 +-+-+-+-+-+-+-+-+ / 1506 / / 1507 / File Path (max 1024 octets,variable length) / 1508 / ... // 1509 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-// 1511 where 1513 +------------+------------------------------------------------------+ 1514 | field | description | 1515 +------------+------------------------------------------------------+ 1516 | Size | the size of the file or directory in octets. | 1517 | Mtime | a timestamp showing when the file or directory was | 1518 | | modified. | 1519 | Ctime | a timestamp of the last status change for this file | 1520 | | or directory. | 1521 | Properties | if set, bit 7 of this field indicates that the entry | 1522 | | corresponds to a directory. Bit 6, if set, | 1523 | | indicates that the file is "special". A special | 1524 | | file may not be directly transferable as it | 1525 | | corresponds to a symbolic link, a named pipe, a | 1526 | | device node, or some other "special" filesystem | 1527 | | object. A file-sender may simply choose not to | 1528 | | include these types of files in the results of a | 1529 | | _getdir_ request. | 1530 | File Path | contains the file's name relative within the | 1531 | | requested path of the _getdir_ transaction, a | 1532 | | maximum of 1024-octet UTF-8 string, that is | 1533 | | null-terminated to indicate the beginning of the | 1534 | | next directory entry in _getdir_ results | 1535 +------------+------------------------------------------------------+ 1536 +-------+-------+---------------------+ 1537 | Bit 6 | Bit 7 | Properties conveyed | 1538 +-------+-------+---------------------+ 1539 | 0 | 0 | normal file. | 1540 | 0 | 1 | normal directory. | 1541 | 1 | 0 | special file. | 1542 | 1 | 1 | special directory. | 1543 +-------+-------+---------------------+ 1545 Whether a particular Directory Entry is being interpreted as the 1546 contents of a METADATA packet, or as the result of a _getdir_ 1547 transaction, the width of the Size field is the same as that used for 1548 all lengths and offsets within the transfer, given by the METADATA 1549 and DATA Flags bits 8 and 9. 1551 Streams listed in a directory should be marked as special. If a 1552 stream is being transferred, its size is unknown -- otherwise it 1553 would be a file. The size property of a Directory Entry for a stream 1554 is therefore expected to be zero. 1556 It is expected that files are only listed in Directory Entries if 1557 they can be transferred to the requester. An implementation only 1558 capable of receiving small files using 16-bit descriptors will only 1559 see small files capable of being transferred to it when browsing the 1560 filesystem of an implementation capable of larger sizes. Directory 1561 sizes are not sent, and a Size of 0 is given instead for directories. 1563 The "epoch" format used in the timestamps for Mtime and Ctime in file 1564 object records is the number of seconds since January 1, 2000 in UTC, 1565 which is the same epoch used in the DTN Bundle Protocol for 1566 timestamps and postpones wrapping for 30 years beyond typical 1970- 1567 based timestamps. This should include all leapseconds. 1569 A file-receiver should preserve the timestamp information received in 1570 the METADATA for its own copy of the file, to allow newer versions of 1571 files to propagate and supercede older versions. 1573 6. Behaviour of a Saratoga Peer 1575 This section describes some details of Saratoga implementations and 1576 uses the RFC 2119 standards language to describe which portions are 1577 needed for interoperability. 1579 6.1. Saratoga Transactions 1581 Following are descriptions of the packet exchanges between two peers 1582 for each type of transaction. Exchanges rely on use of the Id field 1583 to match responses to requests, as described earlier in Section 4.2. 1585 6.1.1. The _get_ Transaction 1587 1. A peer (the file-receiver) sends a REQUEST packet to its peer 1588 (the file-sender). The Flags bits are set to indicate that this 1589 is not a _delete_ request, nor does the File Path indicate a 1590 directory. Each _get_ transaction corresponds to a single file, 1591 and fetching multiple files requires sending multiple REQUEST 1592 packets and using multiple different transaction Ids so that 1593 responses can be differentiated and matched to REQUESTs based on 1594 the Id field. If a specific file is being requested, then its 1595 name is filled into the File Path field, otherwise it is left 1596 null and the file-sender will send a file of its choice. 1598 2. If the request is rejected, then a HOLESTOFILL packet containing 1599 an error code in the Status field is sent and the transaction is 1600 terminated. This HOLESTOFILL packet MUST be sent to reject and 1601 terminate the transaction. The error code MAY make use of the 1602 "Unspecified Error" value for security reasons. Some REQUESTs 1603 might also be rejected for specifying files that are too large to 1604 have their lengths encoded within the maximum integer field width 1605 advertised by bits 8 and 9 of the REQUEST. 1607 3. If the request is accepted, then a HOLESTOFILL packet MUST be 1608 sent with an error code of 0x00 and an In-Response-To field of 1609 zero. 1611 4. Otherwise, if the request is granted, then the file-sender 1612 generates and sends a METADATA packet along with the contents of 1613 the file as a series of DATA packets. In the absence of 1614 HOLESTOFILL packets, if the file-sender believes it has finished 1615 sending the file, it MUST send the last DATA packet with the 1616 Flags bit set requesting a HOLESTOFILL response from the file- 1617 receiver. This can be followed by empty DATA packets with the 1618 Flags bit set requesting a HOLESTOFILL until either a HOLESTOFILL 1619 packet is received, or the inactivity timer expires. All of the 1620 DATA packets MUST use field widths for the file offset descriptor 1621 fields that match what the Flags of the METADATA packet 1622 specified. Some arbitrarily selected DATA packets may have the 1623 Flags bit set that requests a HOLESTOFILL packet. The file- 1624 receiver MAY voluntarily send HOLESTOFILL packets at other times, 1625 where the In-Response-To field MUST set to zero. The file- 1626 receiver SHOULD voluntarily send a HOLESTOFILL packet in response 1627 to the first DATA packet. 1629 5. As the file-receiver takes in the DATA packets, it writes them 1630 into the file locally. The file-receiver keeps track of missing 1631 data in a hole list. Periodically the file sender will set the 1632 ack flag bit in a DATA packet and request a HOLESTOFILL packet 1633 from the file-receiver, with a copy of this hole list. File- 1634 receivers MUST send a HOLESTOFILL packet immediately in response 1635 to receiving a DATA packet with the Flags bit set requesting a 1636 HOLESTOFILL. 1638 6. If the file-sender receives a HOLESTOFILL packet with a non-zero 1639 number of holes, it re-fetches the file data at the specified 1640 offsets and re-transmits it. If the METADATA packet requires 1641 retransmission, this is indicated by a bit in the HOLESTOFILL 1642 packet, and the METADATA packet is retransmitted. The file- 1643 sender MUST retransmit data from any holes reported by the file- 1644 receiver before proceeding further with new DATA packets. 1646 7. When the file-receiver has fully received the file data and the 1647 METADATA packet, then it sends a HOLESTOFILL packet indicating 1648 that the transaction is complete, and it terminates the 1649 transaction locally, although it MUST persist in responding to 1650 any further DATA packets received from the file-sender with 1651 'completed' HOLESTOFILLs, as described in Section 4.5, for some 1652 reasonable amount of time. Starting a timer on sending a 1653 completed HOLESTOFILL and resetting it whenever a received DATA/ 1654 sent 'completed' HOLESTOFILL transaction takes place, then 1655 removing all session state on timer expiry, is one approach to 1656 this. 1658 Given that there may be a high degree of asymmetry in link bandwidth 1659 between the file-sender and file-receiver, the HOLESTOFILL packets 1660 should be carefully generated so as to not congest the feedback path. 1661 This means that both a file-sender should be cautious in setting the 1662 DATA Flags bit requesting HOLESTOFILLs, and also that a file-receiver 1663 should be cautious in gratuitously generating HOLESTOFILL packets of 1664 its own volition. On unidirectional links, a file-sender cannot 1665 reasonably expect to receive HOLESTOFILL packets, so should never 1666 request them. 1668 6.1.2. The _getdir_ Transaction 1670 A _getdir_ transaction proceeds through the same states as the _get_ 1671 transaction. The two differences are that the REQUEST has the 1672 directory bit set in its Flags field, and that, rather than 1673 transferring the contents of a file from the file-receiver to the 1674 file-sender, a set of records representing the contents of a 1675 directory are transferred. These can be parsed and dealt with by the 1676 file-receiver as desired. There is no requirement that a Saratoga 1677 peer send the full contents of a directory listing; a peer may filter 1678 the results to only those entries that are actually accessible to the 1679 requesting peer. 1681 For _getdir_ transactions, the METADATA's bits 8 and 9 in the Flags 1682 field specify both the width of the offset and length fields used 1683 within the transfers DATA and HOLESTOFILL packets, and also the width 1684 of file Size fields within Directory Entries in the interpreted 1685 _getdir_ results. These Flags bits are set to the minimum of the 1686 file-sender's locally-supported maximum width and the advertised 1687 maximum width within the REQUEST packet, and any file system entries 1688 that would normally be contained in the results, but that have sizes 1689 greater than this width can convey, MUST be filtered out. 1691 6.1.3. The _delete_ Transaction 1693 1. A peer sends a REQUEST packet with the bit set indicating that it 1694 is a deletion request and the path to be deleted is filled into 1695 the File Path field. The File Path MUST be filled in for 1696 _delete_ transactions, unlike for _get_ transactions. 1698 2. The other peer replies with a feedback HOLESTOFILL packet whose 1699 Id matches the Id field of the _delete_ REQUEST. This 1700 HOLESTOFILL has a Status code that indicates whether the deletion 1701 was granted and occurred successfully (indicated by the 0x00 1702 Status field in a success HOLESTOFILL), or whether some error 1703 occurred (indicated by the non-zero Status field in a failure 1704 HOLESTOFILL). This HOLESTOFILL packet MUST have no Holes and 16- 1705 bit width zero-valued Progress Indicator and In-Response-To 1706 fields. 1708 If a request is received to delete a file that is already deleted, a 1709 HOLESTOFILL with Status code 0x00 and other fields as described above 1710 is sent back in acknowledgement. This ensures that loss of 1711 HOLESTOFILL acknowledgements and repeated _delete_ requests are 1712 handled properly. 1714 6.1.4. The _put_ Transaction 1716 A _put_ transaction proceeds exactly as a _get_, except the file- 1717 sender and file-receiver roles are exchanged between peers, and no 1718 REQUEST packet is ever sent. The file-sending end senses that the 1719 transaction is in progress when it receives METADATA or DATA packets 1720 for which it has no knowledge of the Id field. If the file-receiver 1721 decides that it will store and handle this request (at least 1722 provisionally), then it MUST send a voluntary (ie, not requested) 1723 success HOLESTOFILL packet to the file-sender. Otherwise, it sends a 1724 failure HOLESTOFILL packet. After sending a failure HOLESTOFILL 1725 packet, it may ignore future packets with the same Id field from the 1726 file-sender, but it should, at a low rate, periodically regenerate 1727 the failure HOLESTOFILL packet if the flow of packets does not stop. 1729 6.2. Beacons 1731 Sending BEACON packets is not needed in any of the transactions 1732 discussed in this specification, but optional BEACONs can provide 1733 useful information in many situations. If a node periodically 1734 generates BEACON packets, then it should do so at a low rate which 1735 does not significantly affect in-progress data transfers. 1737 A node that supports multiple versions of Saratoga (e.g. version 1 1738 from this specification along with the older version 0), MAY send 1739 multiple BEACON packets showing different version numbers. The 1740 version number in a single BEACON should not be used to infer the 1741 larger set of protocol versions that a peer is compatible with. 1743 If a node receives BEACONs from a peer, then it SHOULD NOT attempt to 1744 start any _get_, _getdir_, or _delete_ transactions with that peer if 1745 bit 14 is not set in the latest received BEACONs. Likewise, if 1746 received BEACONs from a peer do not have bit 15 set, then _put_ 1747 transactions SHOULD NOT be attempted to that peer. Unlike the 1748 capabilities bits which prevent certain types of transactions from 1749 being attempted, the willingness bits are advisory, and transactions 1750 MAY be attempted even if the node is not advertising a willingness, 1751 as long as it advertises a capability. This avoids waiting for a 1752 willingness indication across long-delay links. 1754 6.3. Upper-Layer Interface 1756 No particular interface functionality is required in implementations 1757 of this specification. The means and degree of access to Saratoga 1758 configuration settings and transaction control that is offered to 1759 upper layers and applications is completely implementation-dependent. 1760 In general, it is expected that upper layers (or users) can set 1761 timeout values for transaction requests and for inactivity periods 1762 during the transaction, on a per-peer or per-transaction basis, but 1763 in some implementations where the Saratoga code is restricted to run 1764 only over certain interfaces with well-understood operational latency 1765 bounds, then these timers MAY be hard-coded. 1767 6.4. Inactivity Timer 1769 In order to determine the liveliness of a transaction, Saratoga nodes 1770 may implement an inactivity timer for each peer they are expecting to 1771 see packets from. For each packet received from a peer, its 1772 associated inactivity timer is reset. If no packets are received for 1773 some amount of time, and the inactivity timer expires, this serves as 1774 a signal to the node that it should abort (and optionally retry) any 1775 sessions that were in progress with the peer. Information from the 1776 link interface (i.e. link down) can override this timer for point-to- 1777 point links. 1779 The actual length of time that the inactivity timer runs for is a 1780 matter of both implementation and deployment situation. Relatively 1781 short timers (on the order of several round-trip times) allow nodes 1782 to quickly react to loss of contact, while longer timers allow for 1783 transaction robustness in the presence of transient link problems. 1784 This document deliberately does not specify a particular inactivity 1785 timer value nor any rules for setting the inactivity timer, because 1786 the protocol is intended to be used in both long- and short-delay 1787 regimes. 1789 Specifically, the inactivity timer is started on sending REQUEST or 1790 HOLESTOFILL packets. When sending packets not expected to elicit 1791 responses (BEACON, METADATA, or DATA without acknowledgement 1792 requests), there is no point to starting the local inactivity timer. 1794 For normal file transfers, there are simple rules for handling 1795 expiration of the inactivity timer during a _get_ or _put_ 1796 transaction. The file-sender SHOULD terminate the transaction state 1797 and cease to send DATA or METADATA packets. The file-receiver SHOULD 1798 stop sending HOLESTOFILL packets, and MAY choose to store the file in 1799 some cache location so that the transfer can be recovered. This is 1800 possible by waiting for an opportunity to re-attempt the transaction 1801 and immediately sending a HOLESTOFILL that only lists the parts of 1802 the file not yet received if the transaction is granted. In any 1803 case, a partially-received file MUST NOT be handled in any way that 1804 would allow another application to think it is complete. 1806 The file-sender may implement more complex timers to allow rate-based 1807 pacing or simple congestion control using information provided in 1808 HOLESTOFILL packets, but such possible timers and their effects are 1809 deliberately not specified here. 1811 7. Mailing list 1813 There is a mailing list for discussion of Saratoga and its 1814 implementations. Contact Lloyd Wood for details. 1816 8. Security Considerations 1818 The design of Saratoga provides limited, deliberately lightweight, 1819 services for authentication of session requests, and for 1820 authentication or encryption of data files via keyed metadata 1821 checksums. This document does not specify privacy or access control 1822 for data files transferred. Privacy, access, authentication and 1823 encryption issues may be addressed within an implementation or 1824 deployment in several ways that do not affect the file transfer 1825 protocol itself. As examples, IPsec may be used to protect Saratoga 1826 implementations from forged packets, to provide privacy, or to 1827 authenticate the identity of a peer. Other implementation-specific 1828 or configuration-specific mechanisms and policies might also be 1829 employed for authentication and authorization of requests. 1830 Protection of file data and meta-data can also be provided by a 1831 higher-level file encryption facility. If IPsec is not required, use 1832 of encryption before the file is given to Saratoga is preferable. 1833 Basic security practices like not accepting paths with "..", not 1834 following symbolic links, and using a chroot() system call, among 1835 others, should also be considered within an implementation. 1837 Note that Saratoga is intended solely for single-hop transfers 1838 between peers. A METADATA checksum using a previously shared key can 1839 be used to decrypt or authenticate delivered DATA files. Saratoga 1840 can only provide payload encryption across a single link, not end-to- 1841 end across concatenated links through untrusted peers, as checksum 1842 verification of file integrity is required at each node. End-to-end 1843 data encryption, if required, MUST be implemented by the application 1844 using Saratoga. 1846 9. IANA Considerations 1848 IANA has allocated port 7542 (tcp/udp) for use by Saratoga. 1850 saratoga 7542/tcp Saratoga Transfer Protocol 1851 saratoga 7542/udp Saratoga Transfer Protocol 1853 IANA has allocated a dedicated IPv4 all-hosts multicast address 1854 (224.0.0.108) and a dedicated IPv6 link-local multicast addresses 1855 (FF02:0:0:0:0:0:0:6c) for use by Saratoga. 1857 10. Acknowledgements 1859 Developing and deploying the on-orbit IP-based infrastructure of the 1860 Disaster Monitoring Constellation, in which Saratoga has proven 1861 useful, has taken the efforts of hundreds of people over more than a 1862 decade. We thank them all. 1864 We thank James H. McKim as an early contributor to Saratoga 1865 implementations and specifications, while working for RSIS 1866 Information Systems at NASA Glenn. We regard Jim as an author of 1867 this document, but are prevented by the boilerplate five-author limit 1868 from naming him earlier. 1870 We thank Stewart Bryant and Cathryn Peoples for their review 1871 comments. 1873 Work on this document at NASA's Glenn Research Center was funded by 1874 NASA's Earth Science Technology Office (ESTO). 1876 11. A Note on Naming 1878 Saratoga is named for the USS Saratoga (CV-3), the aircraft carrier 1879 sunk at Bikini Atoll that is now a popular diving site. 1881 12. References 1883 12.1. Normative References 1885 [RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768, 1886 August 1980. 1888 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 1889 April 1992. 1891 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1892 Requirement Levels", BCP 14, RFC 2119, March 1997. 1894 [RFC3309] Stone, J., Stewart, R., and D. Otis, "Stream Control 1895 Transmission Protocol (SCTP) Checksum Change", RFC 3309, 1896 September 2002. 1898 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1899 10646", STD 63, RFC 3629, November 2003. 1901 [RFC3828] Larzon, L-A., Degermark, M., Pink, S., Jonsson, L-E., and 1902 G. Fairhurst, "The Lightweight User Datagram Protocol 1903 (UDP-Lite)", RFC 3828, July 2004. 1905 12.2. Informative References 1907 [Hogie05] Hogie, K., Criscuolo, E., and R. Parise, "Using Standard 1908 Internet Protocols and Applications in Space", Computer 1909 Networks, Special Issue on Interplanetary Internet, vol. 1910 47, no. 5, pp. 603-650, April 2005. 1912 [I-D.ietf-ledbat-congestion] 1913 Shalunov, S. and G. Hazel, "Low Extra Delay Background 1914 Transport (LEDBAT)", draft-ietf-ledbat-congestion-02 (work 1915 in progress), July 2010. 1917 [I-D.wood-dtnrg-http-dtn-delivery] 1918 Wood, L. and P. Holliday, "Using HTTP for delivery in 1919 Delay/Disruption-Tolerant Networks", 1920 draft-wood-dtnrg-http-dtn-delivery-05 (work in progress) , 1921 May 2010. 1923 [I-D.wood-dtnrg-saratoga] 1924 Wood, L., McKim, J., Eddy, W., Ivancic, W., and C. 1925 Jackson, "Using Saratoga with a Bundle Agent as a 1926 Convergence Layer for Delay-Tolerant Networking", 1927 draft-wood-dtnrg-saratoga-07 (work in progress) , 1928 May 2010. 1930 [Ivancic10] 1931 Ivancic, W., Eddy, W., Stewart, D., Wood, L., Northam, J., 1932 and C. Jackson, "Experience with delay-tolerant networking 1933 from orbit", International Journal of Satellite 1934 Communications and Networking, Special Issue on best 1935 papers of the Fourth Advanced Satellite Mobile Systems 1936 Conference (ASMS 2008), vol. 28, issues 5-6, pp. 335-351, 1937 September-December 2010. 1939 [Jackson04] 1940 Jackson, C., "Saratoga File Transfer Protocol", Surrey 1941 Satellite Technology Ltd internal technical document , 1942 2004. 1944 [RFC0959] Postel, J. and J. Reynolds, "File Transfer Protocol", 1945 STD 9, RFC 959, October 1985. 1947 [RFC3366] Fairhurst, G. and L. Wood, "Advice to link designers on 1948 link Automatic Repeat reQuest (ARQ)", BCP 62, RFC 3366, 1949 August 2002. 1951 [RFC5050] Scott, K. and S. Burleigh, "Bundle Protocol 1952 Specification", RFC 5050, November 2007. 1954 [RFC5348] Floyd, S., Handley, M., Padhye, J., and J. Widmer, "TCP 1955 Friendly Rate Control (TFRC): Protocol Specification", 1956 RFC 5348, September 2008. 1958 [Wood07a] Wood, L., Ivancic, W., Hodgson, D., Miller, E., Conner, 1959 B., Lynch, S., Jackson, C., da Silva Curiel, A., Cooke, 1960 D., Shell, D., Walke, J., and D. Stewart, "Using Internet 1961 Nodes and Routers Onboard Satellites", International 1962 Journal of Satellite Communications and 1963 Networking, Special Issue on Space Networks, vol. 25, no. 1964 2, pp. 195-216, March/April 2007. 1966 [Wood07b] Wood, L., Eddy, W., Ivancic, W., Miller, E., McKim, J., 1967 and C. Jackson, "Saratoga: a Delay-Tolerant Networking 1968 convergence layer with efficient link utilization", 1969 International Workshop on Satellite and Space 1970 Communications (IWSSC '07) Salzburg, September 2007. 1972 Appendix A. Timestamp/Nonce field considerations 1974 The format of optional timestamps is implementation-dependent. How 1975 the contents of this timestamp field are used and interpreted depends 1976 on local needs and conventions and the local implementation. 1977 However, one simple suggested format for timestamps is to begin with 1978 a POSIX time_t representation of time, in network byte order. This 1979 is either a 32-bit or 64-bit signed integer representing the number 1980 of seconds since 1970. The remainder of this field can be used 1981 either for a representation of elapsed time within the current 1982 second, if that level of accuracy is required, or as a nonce field 1983 uniquely identifying the packet or including other information. Any 1984 locally-meaningful flags identifying a type of timestamp or timebase 1985 can be included before the end of the field. Unused parts of this 1986 field MUST be set to zero. 1988 There are many different representations of timestamps and timebases, 1989 and this draft is too short to cover them in detail. One suggested 1990 flag representation of different timestamp fields is to use the least 1991 significant bits at the end of the timestamp/nonce field as: 1993 +---------+---------------------------------------------------------+ 1994 | Status | Meaning | 1995 | Value | | 1996 +---------+---------------------------------------------------------+ 1997 | 0x00 | No flags set, local interpretation of field. | 1998 | 0x01 | 32-bit timestamp at start of field indicating whole | 1999 | | seconds from epoch. | 2000 | 0x02 | 64-bit timestamp at start of field indicating whole | 2001 | | seconds elapsed from epoch. | 2002 | 0x03 | 32-bit timestamp, as in 0x01, followed by 32-bit | 2003 | | timestamp indicating fraction of the second elapsed. | 2004 | 0x04 | 64-bit timestamp, as in 0x02, followed by 32-bit | 2005 | | timestamp indicating fraction of the second elapsed. | 2006 +---------+---------------------------------------------------------+ 2007 Other values may indicate specific epochs or timebases, as local 2008 requirements dictate. There are many ways to define and use time 2009 usefully. 2011 Timestamp values provide a useful mechanism for Saratoga peers to 2012 measure path and round-trip latency. The use of timestamp values may 2013 assist in developing algorithms for flow control (including TCP- 2014 Friendly Rate Control) or other purposes. 2016 Authors' Addresses 2018 Lloyd Wood 2019 Centre for Communication Systems Research, University of Surrey 2020 Guildford, Surrey GU2 7XH 2021 United Kingdom 2023 Phone: +44-1483-689123 2024 Email: L.Wood@surrey.ac.uk 2026 Wesley M. Eddy 2027 MTI Systems 2028 MS 500-ASRC 2029 NASA Glenn Research Center 2030 21000 Brookpark Road, MS 54-5 2031 Cleveland, OH 44135 2032 USA 2034 Phone: +1-216-433-6682 2035 Email: wes@mti-systems.com 2037 Charles Smith 2038 Commonwealth Scientific and Industrial Research Organisation 2039 Cnr Vimiera and Pembroke Roads 2040 Marsfield, New South Wales 2122 2041 Australia 2043 Phone: +61-404-058974 2044 Email: charles.smith@csiro.au 2045 Will Ivancic 2046 NASA Glenn Research Center 2047 21000 Brookpark Road, MS 54-5 2048 Cleveland, OH 44135 2049 USA 2051 Phone: +1-216-433-3494 2052 Email: William.D.Ivancic@grc.nasa.gov 2054 Chris Jackson 2055 Surrey Satellite Technology Ltd 2056 Tycho House 2057 Surrey Space Centre 2058 20 Stephenson Road 2059 Guildford, Surrey GU2 7YE 2060 United Kingdom 2062 Phone: +44-1483-803803 2063 Email: C.Jackson@sstl.co.uk