idnits 2.17.1 draft-lyon-itp-nodes-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-24) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == Mismatching filename: the document gives the document name as 'draft-lyon-itp-nodes-04', but the file name used is 'draft-lyon-itp-nodes-05' == There is 1 instance of lines with non-ascii characters in the document. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 123 has weird spacing: '...through multi...' == Line 987 has weird spacing: '...ds that conve...' == Line 1191 has weird spacing: '...sending mail ...' -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '1' ** Obsolete normative reference: RFC 2068 (ref. '2') (Obsoleted by RFC 2616) -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 1738 (ref. '4') (Obsoleted by RFC 4248, RFC 4266) -- Possible downref: Non-RFC (?) normative reference: ref. '5' ** Obsolete normative reference: RFC 2141 (ref. '6') (Obsoleted by RFC 8141) -- Possible downref: Non-RFC (?) normative reference: ref. '7' Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Transaction Internet Protocol Working Group J. Lyon 2 Internet-Draft Microsoft 3 Obsoletes K. Evans 4 Expires in 6 months J. Klein 5 Tandem Computers 6 January 26 1998 8 Transaction Internet Protocol 9 Version 3.0 11 13 Status of this Memo 15 This document is an Internet-Draft. Internet-Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas, 17 and its working groups. Note that other groups may also distribute 18 working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or obsoleted by other documents 22 at any time. It is inappropriate to use Internet-Drafts as 23 reference material or to cite them other than as "work in progress." 25 To learn the current status of any Internet-Draft, please check the 26 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 27 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 28 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 29 ftp.isi.edu (US West Coast). 31 Abstract 33 In many applications where different nodes cooperate on some work, 34 there is a need to guarantee that the work happens atomically. That 35 is, each node must reach the same conclusion as to whether the work 36 is to be completed, even in the face of failures. This document 37 proposes a simple, easily-implemented protocol for achieving this 38 end. 40 Table of Contents 42 1. Introduction 3 43 2. Example Usage 3 44 3. Transactions 4 45 4. Connections 4 46 5. Transaction Identifiers 5 47 6. Pushing vs. Pulling Transactions 5 48 7. TIP Transaction Manager Identification and Connection Establishment6 49 8. TIP Uniform Resource Locators 8 50 9. States of a Connection 9 51 10. Protocol Versioning 11 52 11. Commands and Responses 11 53 12. Command Pipelining 12 54 13. TIP Commands 13 55 14. Error Handling 19 56 15. Connection Failure and Recovery 19 57 16. Security Considerations 20 58 17. Significant changes from previous version of this Internet-Draft 23 59 18. References 23 60 19. Authors' Addresses 23 61 20. Comments 24 62 Appendix A. The TIP Multiplexing Protocol Version 2.0. 24 63 1. Introduction 65 The standard method for achieving atomic commitment is the two-phase 66 commit protocol; see [1] for an introduction to atomic commitment 67 and two-phase commit protocols. 69 Numerous two-phase commit protocols have been implemented over the 70 years. However, none of them has become widely used in the 71 Internet, due mainly to their complexity. Most of that complexity 72 comes from the fact that the two-phase commit protocol is bundled 73 together with a specific program-to-program communication protocol, 74 and that protocol lives on top of a very large infrastructure. 76 This memo proposes a very simple two-phase commit protocol. It 77 achieves its simplicity by specifying only how different nodes agree 78 on the outcome of a transaction; it allows (even requires) that the 79 subject matter on which the nodes are agreeing be communicated via 80 other protocols. By doing so, we avoid all of the issues related to 81 application communication semantics and data representation (to name 82 just a few). Independent of the application communication protocol a 83 transaction manager may use the Transport Layer Security protocol 84 [3] to authenticate other transaction managers and encrypt messages. 86 It is envisioned that this protocol will be used mainly for a 87 transaction manager on one Internet node to communicate with a 88 transaction manager on another node. While it is possible to use 89 this protocol for application programs and/or resource managers to 90 speak to transaction managers, this communication is usually intra- 91 node, and most transaction managers already have more-than- adequate 92 interfaces for the task. 94 While we do not expect this protocol to replace existing ones, we do 95 expect that it will be relatively easy for many existing 96 heterogeneous transaction managers to implement this protocol for 97 communication with each other. 99 Further supplemental information regarding the TIP protocol can be 100 found in [5]. 102 2. Example Usage 104 Today the electronic shopping basket is a common metaphor at many 105 electronic store-fronts. Customers browse through an electronic 106 catalog, select goods and place them into an electronic shopping 107 basket. HTTP servers [2] provide various means ranging from URL 108 encoding to context cookies to keep track of client context (e.g. 109 the shopping basket of a customer) and resume it on subsequent 110 customer requests. 112 Once a customer has finished shopping they may decide to commit 113 their selection and place the associated orders. Most orders may 114 have no relationship with each other except being executed as part 115 of the same shopping transaction; others may be dependent on each 116 other (for example, if made as part of a special offering). 118 Irrespective of these details a customer will expect that all orders 119 have been successfully placed upon receipt of a positive 120 acknowledgment. Today's electronic store-fronts must implement 121 their own special protocols to coordinate such placement of all 122 orders. This programming is especially complex when orders are 123 placed through multiple electronic store-fronts. This complexity 124 limits the potential utility of internet applications, and 125 constrains growth. The protocol described in this document intends 126 to provide a standard for Internet servers to achieve agreement on a 127 unit of shared work (e.g. placement of orders in an electronic 128 shopping basket). The server (e.g. a CGI program) placing the 129 orders may want to start a transaction calling its local transaction 130 manager, and ask other servers participating in the work to join the 131 transaction. The server placing the orders passes a reference to 132 the transaction as user data on HTTP requests to the other servers. 133 The other servers call their transaction managers to start a local 134 transaction and ask them to join the remote transaction using the 135 protocol defined in this document. Once all orders have been placed, 136 execution of the two-phase-commit protocol is delegated to the 137 involved transaction managers. If the transaction commits, all 138 orders have been successfully placed and the customer gets a 139 positive acknowledgment. If the transaction aborts no orders will be 140 placed and the customer will be informed of the problem. 142 Transaction support greatly simplifies programming of these 143 applications as exception handling and failure recovery are 144 delegated to a special component. End users are also not left having 145 to deal with the consequences of only partial success. While this 146 example shows how the protocol can be used by HTTP servers, 147 applications may use the protocol when accessing a remote database 148 (e.g. via ODBC), or invoking remote services using other already 149 existing protocols (e.g. RPC). The protocol makes it easy for 150 applications in a heterogeneous network to participate in the same 151 transaction, even if using different communication protocols. 153 3. Transactions 155 "Transaction" is the term given to the programming model whereby 156 computational work performed has atomic semantics. That is, either 157 all work completes successfully and changes are made permanent (the 158 transaction commits), or if any work is unsuccessful, changes are 159 undone (the transaction aborts). The work comprising a transaction 160 (unit of work), is defined by the application. 162 4. Connections 164 The Transaction Internet Protocol (TIP) requires a reliable ordered 165 stream transport with low connection setup costs. In an Internet 166 (IP) environment, TIP operates over TCP, optionally using TLS to 167 provide a secured and authenticated connection, and optionally using 168 a protocol to multiplex light-weight connections over the same TCP 169 or TLS connection. 171 Transaction managers that share transactions establish a TCP (and 172 optionally a TLS) connection. The protocol uses a different 173 connection for each simultaneous transaction shared betwween two 174 transaction managers. After a transaction has ended, the connection 175 can be reused for a different transaction. 177 Optionally, instead of associating a TCP or TLS connection with only 178 a single transaction, two transaction managers may agree on a 179 protocol to multiplex light-weight connections over the same TCP or 180 TLS connection, and associate each simultaneous transaction with a 181 separate light-weight connection. Using light-weight connections 182 reduces latency and resource consumption associated with executing 183 simultaneous transactions. Similar techniques as described here are 184 widely used by existing transaction processing systems. See 185 Appendix A for an example of one such protocol. 187 Note that although the TIP protocol itself is described only in 188 terms of TCP and TLS, there is nothing to preclude the use of TIP 189 with other transport protocols. However, it is up to the implementor 190 to ensure the chosen transport provides equivalent semantics to TCP, 191 and to map the TIP protocol appropriately. 193 In this document the terms "connection" or "TCP connection" can 194 refer to a TIP TCP connection, a TIP TLS connection, or a TIP 195 multiplexing connection (over either TCP or TLS). It makes no 196 difference which, the behavior is the same in each case. Where there 197 are differences in behavior between the connection types, these are 198 stated explicitly. 200 5. Transaction Identifiers 202 Unfortunately, there is no single globally-accepted standard for the 203 format of a transaction identifier; there are various standard and 204 proprietary formats. Allowed formats for a TIP transaction 205 identifier are described below in the section "TIP Uniform Resource 206 Locators". A transaction manager may map its internal transaction 207 identifiers into this TIP format in any manner it sees fit. 208 Furthermore, each party in a superior/subordinate relationship gets 209 to assign its own identifier to the transaction; these identifiers 210 are exchanged when the relationship is first established. Thus, a 211 transaction manager gets to use its own format of transaction 212 identifier internally, but it must remember a foreign transaction 213 identifier for each superior/subordinate relationship in which it is 214 involved. 216 6. Pushing vs. Pulling Transactions 218 Suppose that some program on node "A" has created a transaction, and 219 wants some program on node "B" to do some work as part of the 220 transaction. There are two classical ways that he does this, 221 referred to as the "push" model and the "pull" model. 223 In the "push" model, the program on A first asks his transaction 224 manager to export the transaction to node B. A's transaction 225 manager sends a message to B's TM asking it to instantiate the 226 transaction as a subordinate of A, and return its name for the 227 transaction. The program on A then sends a message to its 228 counterpart on B on the order of "Do some work, and make it part of 229 the transaction that your transaction manager already knows of by 230 the name ...". Because A's TM knows that it sent the transaction to 231 B's TM, A's TM knows to involve B's TM in the two-phase commit 232 process. 234 In the "pull" model, the program on A merely sends a message to B on 235 the order of "Do some work, and make it part of the transaction that 236 my TM knows by the name ...". The program on B asks its TM to 237 enlist in the transaction. At that time, B's TM will "pull" the 238 transaction over from A. As a result of this pull, A's TM knows to 239 involve B's TM in the two-phase commit process. 241 The protocol described here supports both the "push" and "pull" 242 models. 244 7. TIP Transaction Manager Identification and Connection Establishment 246 In order for TIP transaction managers to connect they must be able 247 to identify and locate each other. The information necessary to do 248 this is described by the TIP transaction manager URL. 250 [This specification does not prescribe how TIP transaction managers 251 initially obtain the transaction manager URL (which will probably be 252 via some implementation-specific configuration mechanism).] 254 TIP transaction manager URLs take the form: 256 258 The component comprises: 260 [:] 262 where is either a or an ; and 263 is a decimal number specifying the port at which the transaction 264 manager (or proxy) is listening for requests to establish TIP 265 connections. If the port number is omitted, the standard TIP port 266 number (3371) is used. 268 A is a standard name, acceptable to the domain name 269 service. It must be sufficiently qualified to be useful to the 270 receiver of the command. 272 An is an IP address, in the usual form: four decimal 273 numbers separated by period characters. 275 The component defines the scope (locale) of the 276 component. 278 The component of the transaction manager URL contains data 279 identifying the specific TIP transaction manager, at the location 280 defined by . 282 The component takes the form: 284 [ "/" ] path_segments 286 path_segments = segment *( "/" segment ) 287 segment = *pchar *( ";" param ) 288 param = *pchar 290 pchar = unreserved | escaped | ":" | "@" | "&" | "=" | "+" 291 unreserved = ASCII character octets with values in the range 292 (inclusive): 48-57, 65-90, 97-122 | "$" | "-" | "_" | 293 "." | "!" | "~" | "*" | "'" | "(" | ")" | "," 294 escaped = "%" hex hex 295 hex = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | 296 "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | 297 "e" | "f" 299 The component may consist of a sequence of path segments 300 separated by a single slash "/" character. Within a path segment, 301 the characters "/", ";", "=", and "?" are reserved. Each path 302 segment may include a sequence of parameters, indicated by the 303 semicolon ";" character. The parameters are not significant to the 304 parsing of relative references. 306 [It is intended that the form of the transaction manager URL follow 307 the proposed scheme for Uniform Resource Identifiers (URI).] 309 The TIP transaction manager URL therefore provides to the connection 310 initiator (the primary) the endpoint identifier to be used for the 311 TCP connection (), and to the connection receiver (the 312 secondary) the path to be used to locate the specific TIP 313 transaction manager (). This is all the information required 314 for the connection between the primary and secondary TIP transaction 315 managers to be established. 317 After a connection has been established, the primary party issues an 318 IDENTIFY command. This command includes as parameters two 319 transaction manager URLs: the primary transaction manager URL, and 320 the secondary transaction manager URL. 322 The primary transaction manager URL identifies the TIP transaction 323 manager that initiated the connection. This information is required 324 in certain cases after connection failures, when one of the parties 325 of the connection must re-establish a new connection to the other 326 party in order to complete the two-phase-commit protocol. If the 327 primary party needs to re-establish the connection, the job is easy: 328 a connection is established in the same way as was the original 329 connection. However, if the secondary party needs to re-establish 330 the connection, it must be known how to contact the initiator of the 331 original connection. This information is supplied to the secondary 332 via the primary transaction manager URL on the IDENTIFY command. If 333 a primary transaction manager URL is not supplied, the primary party 334 must not perform any action which would require a connection to be 335 re-established (e.g. to perform recovery actions). 337 The secondary transaction manager URL identifies the receiving TIP 338 transaction manager. In the case of TIP communication via 339 intermediate proxy servers, this URL may be used by the proxy 340 servers to correctly identify and connect to the required TIP 341 transaction manager. 343 8. TIP Uniform Resource Locators 345 Transactions and transaction managers are resources associated with 346 the TIP protocol. Transaction managers and transactions are located 347 using the transaction manager URL scheme. Once a connection has been 348 established, TIP commands may be sent to operate on transactions 349 associated with the respective transaction managers. 351 Applications which want to pull a transaction from a remote node 352 must supply a reference to the remote transaction which allows the 353 local transaction manager (i.e. the transaction manager pulling the 354 transaction) to connect to the remote transaction manager and 355 identify the particular transaction. Applications which want to push 356 a transaction to a remote node must supply a reference to the remote 357 transaction manager (i.e. the transaction manager to which the 358 transaction is to be pushed), which allows the local transaction 359 manager to locate the remote transaction manager. The TIP protocol 360 defines a URL scheme [4] which allows applications and transaction 361 managers to exchange references to transaction managers and 362 transactions. 364 A TIP URL takes the form: 366 TIP://? 368 where identifies the TIP transaction 369 manager (as defined in Section 7 above); and 370 specifies a transaction identifier, which may take one of two forms 371 (standard or non-standard): 373 i. "urn:" ":" 375 A standard transaction identifier, conforming to the proposed 376 Internet Standard for Uniform Resource Names (URNs), as specified 377 by RFC2141; where is the Namespace Identifier, and is 378 the Namespace Specific String. The Namespace ID determines the 379 syntactic interpretation of the Namespace Specific String. The 380 Namespace Specific String is a sequence of characters 381 representing a transaction identifier (as defined by ). The 382 rules for the contents of these fields are specified by [6] 383 (valid characters, encoding, etc.). 385 This format of may be used to express global 386 transaction identifiers in terms of standard representations. 387 Examples for might be or . e.g. 389 TIP://123.123.123.123/?urn:xopen:xid 391 Note that Namespace Ids require registration. See [7] for details 392 on how to do this. 394 ii. 396 A sequence of printable ASCII characters (octets with values in 397 the range 32 through 126 inclusive (excluding ":") representing a 398 transaction identifier. In this non-standard case, it is the 399 combination of and which ensures global uniqueness. e.g. 402 TIP://123.123.123.123/?transid1 404 To create a non-standard TIP URL from a transaction identifier, 405 first replace any reserved characters in the transaction 406 identifier with their equivalent escape sequences, then insert 407 the appropriate transaction manager URL. If the transaction 408 identifier is one that you created, insert your own transaction 409 manager URL. If the transaction identifier is one that you 410 received on a TIP connection that you initiated, use the 411 secondary transaction manager URL that was sent in the IDENTIFY 412 command. If the transaction identifier is one that you received 413 on a TIP connection that you did not initiate, use the primary 414 transaction manager URL that was received in the IDENTIFY 415 command. 417 Except as otherwise described above, the TIP URL scheme follows the 418 rules for reserved characters as defined in [4], and uses escape 419 sequences as defined in [4] Section 5. 421 Note that the TIP protocol itself does not use the TIP URL scheme 422 (it does use the transaction manager URL scheme). The TIP URL scheme 423 is proposed as a standard way to pass transaction identification 424 information through other protocols. e.g. between cooperating 425 application processes. The TIP URL may then be used to communicate 426 to the local transaction manager the information necessary to 427 associate the application with a particular TIP transaction. e.g. to 428 PULL the transaction from a remote transaction manager. It is 429 anticipated that each TIP implementation will provide some set of 430 APIs for this purpose ([5] includes examples of such APIs). 432 9. States of a Connection 434 At any instant, only one party on a connection is allowed to send 435 commands, while the other party is only allowed to respond to 436 commands that he receives. Throughout this document, the party that 437 is allowed to send commands is called "primary"; the other party is 438 called "secondary". Initially, the party that initiated the 439 connection is primary; however, a few commands cause the roles to 440 switch. A connection returns to its original polarity whenever the 441 Idle state is reached. 443 When multiplexing is being used, these rules apply independently to 444 each "virtual" connection, regardless of the polarity of the 445 underlying connection (which will be in the Multiplexing state). 447 Note that commands may be sent "out of band" by the secondary via 448 the use of pipelining. This does not affect the polarity of the 449 connection (i.e. the roles of primary and secondary do not switch). 450 See section 12 for details. 452 In the normal case, TIP connections should only be closed by the 453 primary, when in Initial state. It is generally undesirable for a 454 connection to be closed by the secondary, although this may be 455 necessary in certain error cases. 457 At any instant, a connection is in one of the following states. From 458 the point of view of the secondary party, the state changes when he 459 sends a reply; from the point of view of the primary party, the 460 state changes when he receives a reply. 462 Initial: The initial connection starts out in the Initial state. 463 Upon entry into this state, the party that initiated the 464 connection becomes primary, and the other party becomes 465 secondary. There is no transaction associated with the connection 466 in this state. From this state, the primary can send an IDENTIFY 467 or a TLS command. 469 Idle: In this state, the primary and the secondary have agreed on a 470 protocol version, and the primary supplied an identifier to the 471 secondary party to reconnect after a failure. There is no 472 transaction associated with the connection in this state. Upon 473 entry to this state, the party that initiated the connection 474 becomes primary, and the other party becomes secondary. From this 475 state, the primary can send any of the following commands: BEGIN, 476 MULTIPLEX, PUSH, PULL, QUERY and RECONNECT. 478 Begun: In this state, a connection is associated with an active 479 transaction, which can only be completed by a one-phase protocol. 480 A BEGUN response to a BEGIN command places a connection into this 481 state. Failure of a connection in Begun state implies that the 482 transaction will be aborted. From this state, the primary can 483 send an ABORT, or COMMIT command. 485 Enlisted: In this state, the connection is associated with an active 486 transaction, which can be completed by a one-phase or, two-phase 487 protocol. A PUSHED response to a PUSH command, or a PULLED 488 response to a PULL command, places the connection into this 489 state. Failure of the connection in Enlisted state implies that 490 the transaction will be aborted. From this state, the primary can 491 send an ABORT, COMMIT, or PREPARE command. 493 Prepared: In this state, a connection is associated with a 494 transaction that has been prepared. A PREPARED response to a 495 PREPARE command, or a RECONNECTED response to a RECONNECT command 496 places a connection into this state. Unlike other states, 497 failure of a connection in this state does not cause the 498 transaction to automatically abort. From this state, the primary 499 can send an ABORT, or COMMIT command. 501 Multiplexing: In this state, the connection is being used by a 502 multiplexing protocol, which provides its own set of connections. 503 In this state, no TIP commands are possible on the connection. 504 (Of course, TIP commands are possible on the connections supplied 505 by the multiplexing protocol.) The connection can never leave 506 this state. 508 Tls: In this state, the connection is being used by the TLS 509 protocol, which provides its own secured connection. In this 510 state, no TIP commands are possible on the connection. (Of 511 course, TIP commands are possible on the connection supplied by 512 the TLS protocol.) The connection can never leave this state. 514 Error: In this state, a protocol error has occurred, and the 515 connection is no longer useful. The connection can never leave 516 this state. 518 10. Protocol Versioning 520 This document describes version 3 of the protocol. In order to 521 accommodate future versions, the primary party sends a message 522 indicating the lowest and the highest version number it understands. 523 The secondary responds with the highest version number it 524 understands. 526 After such an exchange, communication can occur using the smaller of 527 the highest version numbers (i.e., the highest version number that 528 both understand). This exchange is mandatory and occurs using the 529 IDENTIFY command (and IDENTIFIED response). 531 If the highest version supported by one party is considered obsolete 532 and no longer supported by the other party, no useful communication 533 can occur. In this case, the newer party should merely drop the 534 connection. 536 11. Commands and Responses 538 All commands and responses consist of one line of ASCII text, using 539 only octets with values in the range 32 through 126 inclusive, 540 followed by either a CR (an octet with value 13) or an LR (an octet 541 with value 10). Each line can be split up into one or more "words", 542 where successive words are separated by one or more space octets 543 (value 32). 545 Arbitrary numbers of spaces at the beginning and/or end of each line 546 are allowed, and ignored. 548 Lines that are empty, or consist entirely of spaces are ignored. 549 (One implication of this is that you can terminate lines with both a 550 CR and an LF if desired; the LF will be treated as terminating an 551 empty line, and ignored.) 553 In all cases, the first word of each line indicates the type of 554 command or response; all defined commands and responses consist of 555 upper-case letters only. 557 For some commands and responses, subsequent words convey parameters 558 for the command or response; each command and response takes a fixed 559 number of parameters. 561 All words on a command or response line after (and including) the 562 first undefined word are totally ignored. These can be used to pass 563 human-readable information for debugging or other purposes. 565 12. Command Pipelining 567 In order to reduce communication latency and improve efficiency, it 568 is possible for multiple TIP "lines" (commands or responses) to be 569 pipelined (concatenated) together and sent as a single message. 570 Lines may also be sent "ahead" (by the secondary, for later 571 procesing by the primary). Examples are an ABORT command immediately 572 followed by a BEGIN command, or a COMMITTED response immediately 573 followed by a PULL command. 575 The sending of pipelined lines is an implementation option. Likewise 576 which lines are pipelined together. Generally, it must be certain 577 that the pipelined line will be valid for the state of the 578 connection at the time it is processed by the receiver. It is the 579 responsibility of the sender to determine this. 581 All implementations must support the receipt of pipelined lines - 582 the rules for processing of which are described by the following 583 paragraph: 585 When the connection state is such that a line should be read 586 (either command or response), then that line (when received) is 587 processed. No more lines are read from the connection until 588 processing again reaches such a state. If a line is received on a 589 connection when it is not the turn of the other party to send, 590 that line is _not_ rejected. Instead, the line is held and 591 processed when the connection state again requires it. The 592 receiving party must process lines and issue responses in the 593 order of lines received. If a line causes an error the connection 594 enters the Error state, and all subsequent lines on the 595 connection are discarded. 597 13. TIP Commands 599 Commands pertain either to connections or transactions. Commands 600 which pertain to connections are: IDENTIFY, MULTIPLEX and TLS. 601 Commands which pertain to transactions are: ABORT, BEGIN, COMMIT, 602 PREPARE, PULL, PUSH, QUERY, and RECONNECT. 604 Following is a list of all valid commands, and all possible 605 responses to each: 607 ABORT 609 This command is valid in the Begun, Enlisted, and Prepared 610 states. It informs the secondary that the current transaction of 611 the connection will abort. Possible responses are: 613 ABORTED 614 The transaction has aborted; the connection enters Idle state. 616 ERROR 617 The command was issued in the wrong state, or was malformed. 618 The connection enters the Error state. 620 BEGIN 622 This command is valid only in the Idle state. It asks the 623 secondary to create a new transaction and associate it with the 624 connection. The newly created transaction will be completed with 625 a one-phase protocol. Possible responses are: 627 BEGUN 628 A new transaction has been successfully begun, and that 629 transaction is now the current transaction of the connection. 630 The connection enters Begun state. 632 NOTBEGUN 633 A new transaction could not be begun; the connection remains 634 in Idle state. 636 ERROR 637 The command was issued in the wrong state, or was malformed. 638 The connection enters the Error state. 640 COMMIT 642 This command is valid in the Begun, Enlisted or Prepared states. 643 In the Begun or Enlisted state, it asks the secondary to attempt 644 to commit the transaction; in the Prepared state, it informs the 645 secondary that the transaction has committed. Note that in the 646 Enlisted state this command represents a one-phase protocol, and 647 should only be done when the sender has 1) no local recoverable 648 resources involved in the transaction, and 2) only one 649 subordinate (the sender will not be involved in any transaction 650 recovery process). Possible responses are: 652 ABORTED 653 This response is possible only from the Begun and Enlisted 654 states. It indicates that some party has vetoed the commitment 655 of the transaction, so it has been aborted instead of 656 committing. The connection enters the Idle state. 658 COMMITTED 659 This response indicates that the transaction has been 660 committed, and that the primary no longer has any 661 responsibilities to the secondary with respect to the 662 transaction. The connection enters the Idle state. 664 ERROR 665 The command was issued in the wrong state, or was malformed. 666 The connection enters the Error state. 668 ERROR 670 This command is valid in any state; it informs the secondary that 671 a previous response was not recognized or was badly formed. A 672 secondary should not respond to this command. The connection 673 enters Error state. 675 IDENTIFY 676 677 678 | "-" 680 This command is valid only in the Initial state. The primary 681 party informs the secondary party of: 1) the lowest and highest 682 protocol version supported (all versions between the lowest and 683 highest must be supported; 2) optionally, an identifier for the 684 primary party at which the secondary party can re-establish a 685 connection if ever needed (the primary transaction manager URL); 686 and 3) an identifier which may be used by intermediate proxy 687 servers to connect to the required TIP transaction manager (the 688 secondary transaction manager URL). If a primary transaction 689 manager URL is not supplied, the secondary party will respond 690 with ABORTED or READONLY to any PREPARE commands. Possible 691 responses are: 693 IDENTIFIED 694 The secondary party has been successfully contacted and has 695 saved the primary transaction manager URL. The response 696 contains the highest protocol version supported by the 697 secondary party. All future communication is assumed to take 698 place using the smaller of the protocol versions in the 699 IDENTIFY command and the IDENTIFIED response. The connection 700 enters the Idle state. 702 NEEDTLS 703 The secondary party is only willing to communicate over TLS 704 secured connections. The connection enters the Tls state, and 705 all subsequent communication is as defined by the TLS 706 protocol. This protocol will begin with the first octet after 707 the line terminator of the IDENTIFY command (for data sent by 708 the primary party), and the first byte after the line 709 terminator of the NEEDTLS response (for data sent by the 710 secondary party). This implies that an implementation must not 711 send both a CR and a LF octet after either the IDENTIFY 712 command or the NEEDTLS response, lest the LF octet be mistaken 713 for the first byte of the TLS protocol. The connection 714 provided by the TLS protocol starts out in the Initial state. 715 After TLS has been negotiated, the primary party must resend 716 the IDENTIFY command. If the primary party cannot support (or 717 refuses to use) the TLS protocol, it closes the connection. 719 ERROR 720 The command was issued in the wrong state, or was malformed. 721 This response also occurs if the secondary party does not 722 support any version of the protocol in the range supported by 723 the primary party. The connection enters the Error state. The 724 primary party should close the connection. 726 MULTIPLEX 728 This command is only valid in the Idle state. The command seeks 729 agreement to use the connection for a multiplexing protocol that 730 will supply a large number of connections on the existing 731 connection. The primary suggests a particular multiplexing 732 protocol. The secondary party can either accept or reject use of 733 this protocol. 735 At the present, the only defined protocol identifier is "TMP2.0", 736 which refers to the TIP Multiplexing Protocol, version 2.0. See 737 Appendix A for details of this protocol. Other protocol 738 identifiers may be defined in the future. 740 If the MULTIPLEX command is accepted, the specified multiplexing 741 protocol will totally control the underlying connection. This 742 protocol will begin with the first octet after the line 743 terminator of the MULTIPLEX command (for data sent by the 744 initiator), and the first byte after the line terminator of the 745 MULTIPLEXING response (for data received by the initiator). This 746 implies that an implementation must not send both a CR and a LF 747 octet after either the MULTIPLEX command or the MULTIPLEXING 748 response, lest the LF octet be mistaken for the first byte of the 749 multiplexing protocol. 751 Note that when using TMP V2.0, a single TIP command (TMP 752 application message) must be wholly contained within a single TMP 753 packet (the TMP PUSH flag is not used by TIP). Possible responses 754 to the MULTIPLEX command are: 756 MULTIPLEXING 757 The secondary party agrees to use the specified multiplexing 758 protocol. The connection enters the Multiplexing state, and 759 all subsequent communication is as defined by that protocol. 760 All connections created by the multiplexing protocol start out 761 in the Idle state. 763 CANTMULTIPLEX 764 The secondary party cannot support (or refuses to use) the 765 specified multiplexing protocol. The connection remains in the 766 Idle state. 768 ERROR 769 The command was issued in the wrong state, or was malformed. 770 The connection enters the Error state. 772 PREPARE 774 This command is valid only in the Enlisted state; it requests the 775 secondary to prepare the transaction for commitment (phase one of 776 two-phase commit). Possible responses are: 778 PREPARED 779 The subordinate has prepared the transaction; the connection 780 enters PREPARED state. 782 ABORTED 783 The subordinate has vetoed committing the transaction. The 784 connection enters the Idle state. After this response, the 785 superior has no responsibilities to the subordinate with 786 respect to the transaction. 788 READONLY 789 The subordinate no longer cares whether the transaction 790 commits or aborts. The connection enters the Idle state. After 791 this response, the superior has no responsibilities to the 792 subordinate with respect to the transaction. 794 ERROR 795 The command was issued in the wrong state, or was malformed. 796 The connection enters the Error state. 798 PULL 799 801 This command is only valid in Idle state. This command seeks to 802 establish a superior/subordinate relationship in a transaction, 803 with the primary party of the connection as the subordinate 804 (i.e., he is pulling a transaction from the secondary party). 805 Note that the entire value of (as defined in 806 the section "TIP Uniform Resource Locators") must be specified as 807 the transaction identifier. Possible responses are: 809 PULLED 810 The relationship has been established. Upon receipt of this 811 response, the specified transaction becomes the current 812 transaction of the connection, and the connection enters 813 Enlisted state. Additionally, the roles of primary and 814 secondary become reversed. (That is, the superior becomes the 815 primary for the connection.) 817 NOTPULLED 818 The relationship has not been established (possibly, because 819 the secondary party no longer has the requested transaction). 820 The connection remains in Idle state. 822 ERROR 823 The command was issued in the wrong state, or was malformed. 824 The connection enters the Error state. 826 PUSH 828 This command is valid only in the Idle state. It seeks to 829 establish a superior/subordinate relationship in a transaction 830 with the primary as the superior. Note that the entire value of 831 (as defined in the section "TIP Uniform 832 Resource Locators") must be specified as the transaction 833 identifier. Possible responses are: 835 PUSHED 836 The relationship has been established, and the identifier by 837 which the subordinate knows the transaction is returned. The 838 transaction becomes the current transaction for the 839 connection, and the connection enters Enlisted state. 841 ALREADYPUSHED 842 The relationship has been established, and the identifier by 843 which the subordinate knows the transaction is returned. 844 However, the subordinate already knows about the transaction, 845 and is expecting the two-phase commit protocol to arrive via a 846 different connection. In this case, the connection remains in 847 the Idle state. 849 NOTPUSHED 850 The relationship could not be established. The connection 851 remains in the Idle state. 853 ERROR 854 The command was issued in the wrong state, or was malformed. 855 The connection enters Error state. 857 QUERY 859 This command is valid only in the Idle state. A subordinate uses 860 this command to determine whether a specific transaction still 861 exists at the superior. Possible responses are: 863 QUERIEDEXISTS 864 The transaction still exists. The connection remains in the 865 Idle state. 867 QUERIEDNOTFOUND 868 The transaction no longer exists. The connection remains in 869 the Idle state. 871 ERROR 872 The command was issued in the wrong state, or was malformed. 873 The connection enters Error state. 875 RECONNECT 877 This command is valid only in the Idle state. A superior uses the 878 command to re-establish a connection for a transaction, when the 879 previous connection was lost during Prepared state. Possible 880 responses are: 882 RECONNECTED 883 The subordinate accepts the reconnection. The connection 884 enters Prepared state. 886 NOTRECONNECTED 887 The subordinate no longer knows about the transaction. The 888 connection remains in Idle state. 890 ERROR 891 The command was issued in the wrong state, or was malformed. 892 The connection enters Error state. 894 TLS 896 This command is valid only in the Initial state. A primary uses 897 this command to attempt to establish a secured connection using 898 TLS. 900 If the TLS command is accepted, the TLS protocol will totally 901 control the underlying connection. This protocol will begin with 902 the first octet after the line terminator of the TLS command (for 903 data sent by the primary), and the first byte after the line 904 terminator of the TLSING response (for data received by the 905 primary). This implies that an implementation must not send both 906 a CR and a LF octet after either the TLS command or the TLSING 907 response, lest the LF octet be mistaken for the first byte of the 908 TLS protocol. 910 Possible responses to the TLS command are: 912 TLSING 913 The secondary party agrees to use the TLS protocol[3]. The 914 connection enters the Tls state, and all subsequent 915 communication is as defined by the TLS protocol. The 916 connection provided by the TLS protocol starts out in the 917 Initial state. 919 CANTTLS 920 The secondary party cannot support (or refuses to use) the TLS 921 protocol. The connection remains in the Initial state. 923 ERROR 924 The command was issued in the wrong state, or was malformed. 925 The connection enters the Error state. 927 14. Error Handling 929 If either party receives a line that it cannot understand it closes 930 the connection. If either party (either a command or a response), 931 receives an ERROR indication or an ERROR response on a connection 932 the connection enters the Error state and no further communication 933 is possible on that connection. An implementation may decide to 934 close the connection. Closing of the connection is treated by the 935 other party as a communication failure. 937 Receipt of an ERROR indication or an ERROR response indicates that 938 the other party believes that you have not properly implemented the 939 protocol. 941 15. Connection Failure and Recovery 943 A connection failure may be caused by a communication failure, or by 944 any party closing the connection. It is assumed TIP implementations 945 will use some private mechanism to detect TIP connection failure 946 (e.g. socket keepalive, or a timeout scheme). 948 Depending on the state of a connection, transaction managers will 949 need to take various actions when a connection fails. 951 If the connection fails in Initial or Idle state, the connection 952 does not refer to a transaction. No action is necessary. 954 If the connection fails in the Multiplexing state, all connections 955 provided by the multiplexing protocol are assumed to have failed. 956 Each of them will be treated independently. 958 If the connection fails in Begun or Enlisted state and COMMIT has 959 been sent, then transaction completion has been delegated to the 960 subordinate (the superior is not involved); the outcome of the 961 transaction is unknown by the superior (it is known at the 962 subordinate). The superior uses application-specific means to 963 determine the outcome of the transaction (note that transaction 964 integrity is not compromised in this case since the superior has no 965 recoverable resources involved in the transaction). If the 966 connection fails in Begun or Enlisted state and COMMIT has not been 967 sent, the transaction will be aborted. 969 If the connection fails in Prepared state, then the appropriate 970 action is different for the superior and subordinate in the 971 transaction. 973 If the superior determines that the transaction commits, then it 974 must eventually establish a new connection to the subordinate, and 975 send a RECONNECT command for the transaction. If it receives a 976 NOTRECONNECTED response, it need do nothing else. However, if it 977 receives a RECONNECTED response, it must send a COMMIT request and 978 receive a COMMITTED response. 980 If the superior determines that the transaction aborts, it is 981 allowed to (but not required to) establish a new connection and send 982 a RECONNECT command for the transaction. If it receives a 983 RECONNECTED response, it should send an ABORT command. 985 The above definition allows the superior to reestablish the 986 connection before it knows the outcome of the transaction, if it 987 finds that convenient. Having succeeded in a RECONNECT command, the 988 connection is back in Prepared state, and the superior can send a 989 COMMIT or ABORT command as appropriate when it knows the transaction 990 outcome. 992 Note that it is possible for a RECONNECT command to be received by 993 the subordinate before it is aware that the previous connection has 994 failed. In this case the subordinate treats the RECONNECT command as 995 a failure indication and cleans-up any resources associated with the 996 connection, and associates the transaction state with the new 997 connection. 999 If a subordinate notices a connection failure in Prepared state, 1000 then it should periodically attempt to create a new connection to 1001 the superior and send a QUERY command for the transaction. It should 1002 continue doing this until one of the following two events occurs: 1004 1. It receives a QUERIEDNOTFOUND response from the superior. In this 1005 case, the subordinate should abort the transaction. 1007 2. The superior, on some connection that it initiated, sends a 1008 RECONNECT command for the transaction to the subordinate. In this 1009 case, the subordinate can expect to learn the outcome of the 1010 transaction on this new connection. If this new connection should 1011 fail before the subordinate learns the outcome of the 1012 transaction, it should again start sending QUERY commands. 1014 Note that if a TIP system receives either a QUERY or a RECONNECT 1015 command, and for some reason is unable to satisfy the request (e.g. 1016 the necessary recovery information is not currently available), then 1017 the connection should be dropped. 1019 16. Security Considerations 1021 This section is meant to inform application developers, transaction 1022 manager developers, and users of the security implications of TIP as 1023 described by this document. The discussion does not include 1024 definitive solutions to the issues described, though it does make 1025 some suggestions for reducing security risks. 1027 As with all two phase-commit protocols, any security mechanisms 1028 applied to the application communication protocol are liable to be 1029 subverted unless corresponding mechanisms are applied to the 1030 commitment protocol. For example, any authentication between the 1031 parties using the application protocol must be supported by security 1032 of the TIP exchanges to at least the same level of certainty. 1034 16.1. TLS, Mutual Authentication and Authorization 1036 TLS provides optional client-side authentication, optional server- 1037 side authentication, and optional packet encryption. 1039 A TIP implementation may refuse to provide service unless TLS is 1040 being used. It may refuse to provide service if packet encryption is 1041 not being used. It may refuse to provide service unless the remote 1042 party has been authenticated (via TLS). 1044 A TIP implementation should be willing to be authenticated itself 1045 (via TLS). This is true regardless of whether the implementation is 1046 acting as a client or a server. 1048 Once a remote party has been authenticated, a TIP transaction 1049 manager may use that remote party�s identity to decide what 1050 operations to allow. 1052 Whether TLS is to be used on a connection, and if so, how TLS is to 1053 be used, and what operations are to subsequently be allowed, is 1054 determined by the security policies of the connecting TIP 1055 transaction managers towards each other. How these security policies 1056 are defined, and how a TIP transaction manager learns of them is 1057 totally private to the implementation and beyond the scope of this 1058 document. 1060 16.2. PULL-Based Denial-of-Service Attack 1062 Assume that a malicious user knows the identity of a transaction 1063 that is currently active in some transaction manager. If the 1064 malefactor opens a TIP connection to the transaction manager, sends 1065 a PULL command, then closes the connection, he can cause that 1066 transaction to be aborted. This results in a denial of service to 1067 the legitimate owner of the transaction. 1069 An implementation may avoid this attack by refusing PULL commands 1070 unless TLS is being used, the remote party has been authenticated, 1071 and the remote party is trusted. 1073 16.3. PUSH-Based Denial-of-Service Attack 1075 When the connection between two transaction managers is closed while 1076 a transaction is in the Prepared state, each transaction manager 1077 needs to remember information about the transaction until a 1078 connection can be re-established. 1080 If a malicious user exploits this fact to repeatedly create 1081 transactions, get them into Prepared state and drop the connection, 1082 he may cause a transaction manager to suffer resource exhaustion, 1083 thus denying service to all legitimate users of that transaction 1084 manager. 1086 An implementation may avoid this attack by refusing PUSH commands 1087 unless TLS is being used, the remote party has been authenticated, 1088 and the remote party is trusted. 1090 16.4. Transaction Corruption Attack 1092 If a subordinate transaction manager has lost its connection for a 1093 particular prepared transaction, a malicious user can initiate a TIP 1094 connection to the transaction manager, and send it a RECONNECT 1095 command followed by either a COMMIT or an ABORT command for the 1096 transaction. The malicious user could thus cause part of a 1097 transaction to be committed when it should have been aborted, or 1098 vice versa. 1100 An implementation may avoid this attack by recording the 1101 authenticated identity of its superior in a transaction, and by 1102 refusing RECONNECT commands unless TLS is being used and the 1103 authenticated identity of the remote party is the same as the 1104 identity of the original superior. 1106 16.5. Packet-Sniffing Attacks 1108 If a malicious user can intercept traffic on a TIP connection, he 1109 may be able to deduce information useful in planning other attacks. 1110 For example, if comment fields include the product name and version 1111 number of a transaction manager, a malicious user might be able to 1112 use this information to determine what security bugs exist in the 1113 implementation. 1115 An implementation may avoid this attack by always using TLS to 1116 provide session encryption, and by not putting any personalizing 1117 information on the TLS/TLSING command/response pair. 1119 16.6. Man-in-the-Middle Attack 1121 If a malicious user can intercept and alter traffic on a TIP 1122 connection, he can wreak havoc in a number of ways. For example, he 1123 could replace a COMMIT command with an ABORT command. 1125 An implementation may avoid this attack by always using TLS to 1126 provide session encryption and authentication of the remote party. 1128 17. Significant changes from previous version of this Internet-Draft 1130 Added negotiated TLS security protocol exchange (replaces TIPS: URL 1131 and dual port scheme). 1133 Replaced Security Considerations section. 1135 Modified TIP endpoint identifiers to use URI-type transaction 1136 manager URL scheme. 1138 Protocol Version number is now 3. 1140 Other minor clarifications. 1142 18. References 1144 [1] Gray, J. and A. Reuter (1993), Transaction Processing: Concepts 1145 and Techniques. San Francisco, CA: Morgan Kaufmann Publishers. 1146 (ISBN 1-55860-190-2). 1148 [2] RFC2068 Standards Track "Hypertext Transfer Protocol -- 1149 HTTP/1.1". 1150 R. Fielding et al. 1152 [3] Internet-Draft "The TLS Protocol Version 1.0". T. Dierks et al. 1154 [4] RFC1738 Standards Track "Uniform Resource Locators (URL)". 1155 T. Berners-Lee et al. 1157 [5] Internet-Draft "Transaction Internet Protocol - Requirements 1158 and Supplemental Information". K. Evans et al. 1160 [6] RFC2141 "URN Syntax". R. Moats. 1162 [7] Internet-Draft "Namespace Identifier Requirements for URN 1163 Services". 1164 P. Faltstrom et al. 1166 19. Authors' Addresses 1168 Jim Lyon Keith Evans 1169 Microsoft Corporation Tandem Computers, Inc. 1170 One Microsoft Way 5425 Stevens Creek Blvd 1171 Redmond, WA 98052-6399, USA Santa Clara, CA 95051-7200, USA 1172 Phone: +1 (206) 936 0867 Phone: +1 (408) 285 5314 1173 Fax: +1 (206) 936 7329 Fax: +1 (408) 285 5245 1174 Email: JimLyon@Microsoft.Com Email: Keith@Loc252.Tandem.Com 1176 Johannes Klein 1177 Tandem Computers Inc. 1179 10555 Ridgeview Court 1180 Cupertino, CA 95014-0789, USA 1181 Phone: +1 (408) 285 0453 1182 Fax: +1 (408) 285 9818 1183 Email: Klein_Johannes@Tandem.Com 1185 20. Comments 1187 Please send comments on this document to the authors at 1188 , , 1189 , or to the TIP mailing list at 1190 . You can subscribe to the TIP mailing list by 1191 sending mail to with the line 1192 "subscribe tip " somewhere in the body of the message. 1194 Appendix A. The TIP Multiplexing Protocol Version 2.0. 1196 This appendix describes version 2.0 of the TIP Multiplexing Protocol 1197 (TMP). TMP is intended solely for use with the TIP protocol, and 1198 forms part of the TIP protocol specification (although its 1199 implementation is optional). TMP V2.0 is the only multiplexing 1200 protocol supported by TIP V3.0. 1202 Abstract 1204 TMP provides a simple mechanism for creating multiple lightweight 1205 connections over a single TCP connection. Several such lightweight 1206 connections can be active simultaneously. TMP provides a byte 1207 oriented service, but allows message boundaries to be marked. 1209 A.1. Introduction 1211 There are several protocols in widespread use on the Internet which 1212 create a single TCP connection for each transaction. Unfortunately, 1213 because these transactions are short lived, the cost of setting up 1214 and tearing down these TCP connections becomes significant, both in 1215 terms of resources used and in the delays associated with TCP's 1216 congestion control mechanisms. 1218 The TIP Multiplexing Protocol (TMP) is a simple protocol running on 1219 top of TCP that can be used to create multiple lightweight 1220 connections over a single transport connection. TMP therefore 1221 provides for more efficient use of TCP connections. Data from 1222 several different TMP connections can be interleaved, and both 1223 message boundaries and end of stream markers can be provided. 1225 Because TMP runs on top of a reliable byte ordered transport service 1226 it can avoid most of the extra work TCP must go through in order to 1227 ensure reliability. For example, TMP connections do not need to be 1228 confirmed, so there is no need to wait for handshaking to complete 1229 before data can be sent. 1231 Note: TMP is not intended as a generalized multiplexing protocol. If 1232 you are designing a different protocol that needs multiplexing, TMP 1233 may or may not be appropriate. Protocols with large messages can 1234 exceed the buffering capabilities of the receiver, and under certain 1235 conditions this can cause deadlock. TMP when used with TIP does not 1236 suffer from this problem since TIP is a request-response protocol, 1237 and all messages are short. 1239 A.2. Protocol Model 1241 The basic protocol model is that of multiple lightweight connections 1242 operating over a reliable stream of bytes. The party which initiated 1243 the connection is referred to as the primary, and the party which 1244 accepted the connection is referred to as the secondary. 1246 Connections may be unidirectional or bi-directional; each end of a 1247 bi-directional connection may be closed separately. Connections may 1248 be closed normally, or reset to indicate an abortive release. 1249 Aborting a connection closes both data streams. 1251 Once a connection has been opened, applications can send messages 1252 over it, and signal the end of application level messages. 1253 Application messages are encapsulated in TMP packets and transferred 1254 over the byte stream. A single TIP command (TMP application message) 1255 must be wholly contained within a single TMP packet. 1257 A.3. TMP Packet Format 1259 A TMP packet consists of a 64 bit header followed by zero or more 1260 octets of data. The header contains three fields; a flag byte, the 1261 connection identifier, and the packet length. Both integers, the 1262 connection identifier and the packet length must be sent in network 1263 byte order. 1265 FLAGS 1266 +--------+--------+--------+--------+ 1267 |SFPR0000| Connection ID | 1268 +--------+--------+--------+--------+ 1269 | | Length | 1270 +--------+--------+--------+--------+ 1272 A.3.1. Flag Details 1274 +-------+-----------+-----------------------------------------+ 1275 | Name | Mask | Description | 1276 +-------+-----------+ ----------------------------------------+ 1277 | SYN | 1xxx|0000 | Open a new connection | 1278 | FIN | x1xx|0000 | Close an existing connection | 1279 | PUSH | xx1x|0000 | Mark application level message boundary | 1280 | RESET | xxx1|0000 | Abort the connection | 1281 +-------+-----------+-----------------------------------------+ 1283 A.4. Connection Identifiers 1285 Each TMP connection is identified by a 24 bit integer. TMP 1286 connections created by the party which initiated the underlying TCP 1287 connection must have even identifiers; those created by the other 1288 party must have odd identifiers. 1290 A.5. TMP Connection States 1292 TMP connections can exist in several different states; Closed, 1293 OpenWrite, OpenSynRead, OpenSynReset, OpenReadWrite, CloseWrite, and 1294 CloseRead. A connection can change its state in response to 1295 receiving a packet with the SYN, FIN, or RESET bits set, or in 1296 response to an API call by the application. The available API calls 1297 are open, close, and abort. 1299 The meaning of most states is obvious (e.g. OpenWrite means that a 1300 connection has been opened for writing). The meaning of the states 1301 OpenSynRead and OpenResetRead need more explanation. 1303 In the OpenSynRead state a primary opened and immediately closed the 1304 output data stream of a connection, and is now waiting for a SYN 1305 response from the secondary to open the input data stream for 1306 reading. 1308 In the OpenResetRead state a primary opened and immediately aborted 1309 a connection, and is now waiting for a SYN response from the 1310 secondary to finally close the connection. 1312 A.6. Event Priorities and State Transitions 1314 The state table shown below describes the actions and state 1315 transitions that occur in response to a given event. The events 1316 accepted by each state are listed in priority order with highest 1317 priority first. If multiple events are present in a message, those 1318 events matching the list are processed. If multiple events match, 1319 the event with the highest priority is accepted and processed first. 1320 Any remaining events are processed in the resultant successor state. 1322 For example, if a TMP connection at the secondary is in the Closed 1323 state, and the secondary receives a packet containing a SYN event, a 1324 FIN event and an input data event (i.e. DATA-IN), the secondary 1325 first accepts the SYN event (because it is the only match in Closed 1326 state). The secondary accepts the connection, sends a SYN event and 1327 enters the ReadWrite state. The SYN event is removed from the list 1328 of pending events. The remaining events are FIN and DATA-IN. In the 1329 ReadWrite state the secondary reads the input data (i.e. the DATA-IN 1330 event is processed first because it has higher priority than the FIN 1331 event). Once the data has been read and the DATA-IN event has been 1332 removed from the list of pending events, the FIN event is processed 1333 and the secondary enters the CloseWrite state. 1335 If the secondary receives a packet containing a SYN event, and is 1336 for some reason unable to accept the connection (e.g. insufficient 1337 resources), it should reject the request by sending a SYN event 1338 followed by a RESET event. Note that both events can be sent as part 1339 of the same TMP packet. 1341 If either party receives a TMP packet that it does not understand, 1342 or an event in an incorrect state, it closes the TCP connection. 1344 +==============+=========+==========+==============+ 1345 | Entry State | Event | Action | Exit State | 1346 +==============+=========+==========+==============+ 1347 | Closed | SYN | SYN | ReadWrite | 1348 | | OPEN | SYN | OpenWrite | 1349 +--------------+---------+----------+--------------+ 1350 | OpenWrite | SYN | Accept | ReadWrite | 1351 | | WRITE | DATA-OUT | OpenWrite | 1352 | | CLOSE | FIN | OpenSynRead | 1353 | | ABORT | RESET | OpenSynReset | 1354 +--------------+---------+----------+--------------+ 1355 | OpenSynRead | SYN | Accept | CloseRead | 1356 +--------------+---------+----------+--------------+ 1357 | OpenSynReset | SYN | Accept | Closed | 1358 +--------------+---------+----------+--------------+ 1359 | ReadWrite | DATA-IN | Accept | ReadWrite | 1360 | | FIN | Accept | CloseWrite | 1361 | | RESET | Accept | Closed | 1362 | | WRITE | DATA-OUT | ReadWrite | 1363 | | CLOSE | FIN | CloseRead | 1364 | | ABORT | RESET | Closed | 1365 +--------------+---------+----------+--------------+ 1366 | CloseWrite | RESET | Accept | Closed | 1367 | | WRITE | DATA-OUT | CloseWrite | 1368 | | CLOSE | FIN | Closed | 1369 | | ABORT | RESET | Closed | 1370 +--------------+---------+----------+--------------+ 1371 | CloseRead | DATA-IN | Accept | CloseRead | 1372 | | FIN | Accept | Closed | 1373 | | RESET | Accept | Closed | 1374 | | ABORT | RESET | Closed | 1375 +--------------+---------+----------+--------------+ 1377 TMP Event Priorities and State Transitions