idnits 2.17.1 draft-lyon-itp-nodes-06.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-26) 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-05', but the file name used is 'draft-lyon-itp-nodes-06' == 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 122 has weird spacing: '...through multi...' == Line 997 has weird spacing: '...ds that conve...' == Line 1196 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.) -- The document date (February 6, 1998) is 9576 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- 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' -- Possible downref: Non-RFC (?) normative reference: ref. '8' -- Possible downref: Non-RFC (?) normative reference: ref. '9' Summary: 10 errors (**), 0 flaws (~~), 6 warnings (==), 8 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 February 6, 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 & Connection Establishment 6 49 8. TIP Uniform Resource Locators 8 50 9. States of a Connection 10 51 10. Protocol Versioning 11 52 11. Commands and Responses 12 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 21 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). 117 Irrespective of these details a customer will expect that all orders 118 have been successfully placed upon receipt of a positive 119 acknowledgment. Today's electronic store-fronts must implement 120 their own special protocols to coordinate such placement of all 121 orders. This programming is especially complex when orders are 122 placed through multiple electronic store-fronts. This complexity 123 limits the potential utility of internet applications, and 124 constrains growth. The protocol described in this document intends 125 to provide a standard for Internet servers to achieve agreement on a 126 unit of shared work (e.g. placement of orders in an electronic 127 shopping basket). The server (e.g. a CGI program) placing the 128 orders may want to start a transaction calling its local transaction 129 manager, and ask other servers participating in the work to join the 130 transaction. The server placing the orders passes a reference to 131 the transaction as user data on HTTP requests to the other servers. 132 The other servers call their transaction managers to start a local 133 transaction and ask them to join the remote transaction using the 134 protocol defined in this document. Once all orders have been placed, 135 execution of the two-phase-commit protocol is delegated to the 136 involved transaction managers. If the transaction commits, all 137 orders have been successfully placed and the customer gets a 138 positive acknowledgment. If the transaction aborts no orders will be 139 placed and the customer will be informed of the problem. 141 Transaction support greatly simplifies programming of these 142 applications as exception handling and failure recovery are 143 delegated to a special component. End users are also not left having 144 to deal with the consequences of only partial success. While this 145 example shows how the protocol can be used by HTTP servers, 146 applications may use the protocol when accessing a remote database 147 (e.g. via ODBC), or invoking remote services using other already 148 existing protocols (e.g. RPC). The protocol makes it easy for 149 applications in a heterogeneous network to participate in the same 150 transaction, even if using different communication protocols. 152 3. Transactions 154 "Transaction" is the term given to the programming model whereby 155 computational work performed has atomic semantics. That is, either 156 all work completes successfully and changes are made permanent (the 157 transaction commits), or if any work is unsuccessful, changes are 158 undone (the transaction aborts). The work comprising a transaction 159 (unit of work), is defined by the application. 161 4. Connections 163 The Transaction Internet Protocol (TIP) requires a reliable ordered 164 stream transport with low connection setup costs. In an Internet 165 (IP) environment, TIP operates over TCP, optionally using TLS to 166 provide a secured and authenticated connection, and optionally using 167 a protocol to multiplex light-weight connections over the same TCP 168 or TLS connection. 170 Transaction managers that share transactions establish a TCP (and 171 optionally a TLS) connection. The protocol uses a different 172 connection for each simultaneous transaction shared betwween two 173 transaction managers. After a transaction has ended, the connection 174 can be reused for a different transaction. 176 Optionally, instead of associating a TCP or TLS connection with only 177 a single transaction, two transaction managers may agree on a 178 protocol to multiplex light-weight connections over the same TCP or 179 TLS connection, and associate each simultaneous transaction with a 180 separate light-weight connection. Using light-weight connections 181 reduces latency and resource consumption associated with executing 182 simultaneous transactions. Similar techniques as described here are 183 widely used by existing transaction processing systems. See 184 Appendix A for an example of one such protocol. 186 Note that although the TIP protocol itself is described only in 187 terms of TCP and TLS, there is nothing to preclude the use of TIP 188 with other transport protocols. However, it is up to the implementor 189 to ensure the chosen transport provides equivalent semantics to TCP, 190 and to map the TIP protocol appropriately. 192 In this document the terms "connection" or "TCP connection" can 193 refer to a TIP TCP connection, a TIP TLS connection, or a TIP 194 multiplexing connection (over either TCP or TLS). It makes no 195 difference which, the behavior is the same in each case. Where there 196 are differences in behavior between the connection types, these are 197 stated explicitly. 199 5. Transaction Identifiers 201 Unfortunately, there is no single globally-accepted standard for the 202 format of a transaction identifier; there are various standard and 203 proprietary formats. Allowed formats for a TIP transaction 204 identifier are described below in the section "TIP Uniform Resource 205 Locators". A transaction manager may map its internal transaction 206 identifiers into this TIP format in any manner it sees fit. 207 Furthermore, each party in a superior/subordinate relationship gets 208 to assign its own identifier to the transaction; these identifiers 209 are exchanged when the relationship is first established. Thus, a 210 transaction manager gets to use its own format of transaction 211 identifier internally, but it must remember a foreign transaction 212 identifier for each superior/subordinate relationship in which it is 213 involved. 215 6. Pushing vs. Pulling Transactions 217 Suppose that some program on node "A" has created a transaction, and 218 wants some program on node "B" to do some work as part of the 219 transaction. There are two classical ways that he does this, 220 referred to as the "push" model and the "pull" model. 222 In the "push" model, the program on A first asks his transaction 223 manager to export the transaction to node B. A's transaction 224 manager sends a message to B's TM asking it to instantiate the 225 transaction as a subordinate of A, and return its name for the 226 transaction. The program on A then sends a message to its 227 counterpart on B on the order of "Do some work, and make it part of 228 the transaction that your transaction manager already knows of by 229 the name ...". Because A's TM knows that it sent the transaction to 230 B's TM, A's TM knows to involve B's TM in the two-phase commit 231 process. 233 In the "pull" model, the program on A merely sends a message to B on 234 the order of "Do some work, and make it part of the transaction that 235 my TM knows by the name ...". The program on B asks its TM to 236 enlist in the transaction. At that time, B's TM will "pull" the 237 transaction over from A. As a result of this pull, A's TM knows to 238 involve B's TM in the two-phase commit process. 240 The protocol described here supports both the "push" and "pull" 241 models. 243 7. TIP Transaction Manager Identification and Connection Establishment 245 In order for TIP transaction managers to connect they must be able 246 to identify and locate each other. The information necessary to do 247 this is described by the TIP transaction manager URL. 249 [This specification does not prescribe how TIP transaction managers 250 initially obtain the transaction manager URL (which will probably be 251 via some implementation-specific configuration mechanism).] 253 TIP transaction manager URLs take the form: 255 257 The component comprises: 259 [:] 261 where is either a or an ; and 262 is a decimal number specifying the port at which the transaction 263 manager (or proxy) is listening for requests to establish TIP 264 connections. If the port number is omitted, the standard TIP port 265 number (3371) is used. 267 A is a standard name, acceptable to the domain name 268 service. It must be sufficiently qualified to be useful to the 269 receiver of the command. 271 An is an IP address, in the usual form: four decimal 272 numbers separated by period characters. 274 The component defines the scope (locale) of the 275 component. 277 The component of the transaction manager URL contains data 278 identifying the specific TIP transaction manager, at the location 279 defined by . 281 The component takes the form: 283 "/" [path_segments] 285 path_segments = segment *( "/" segment ) 286 segment = *pchar *( ";" param ) 287 param = *pchar 289 pchar = unreserved | escaped | ":" | "@" | "&" | "=" | "+" 290 unreserved = ASCII character octets with values in the range 291 (inclusive): 48-57, 65-90, 97-122 | "$" | "-" | "_" | 292 "." | "!" | "~" | "*" | "'" | "(" | ")" | "," 293 escaped = "%" hex hex 294 hex = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | 295 "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | 296 "e" | "f" 298 The component may consist of a sequence of path segments 299 separated by a single slash "/" character. Within a path segment, 300 the characters "/", ";", "=", and "?" are reserved. Each path 301 segment may include a sequence of parameters, indicated by the 302 semicolon ";" character. The parameters are not significant to the 303 parsing of relative references. 305 [It is intended that the form of the transaction manager URL follow 306 the proposed scheme for Uniform Resource Identifiers (URI) [8].] 308 The TIP transaction manager URL therefore provides to the connection 309 initiator (the primary) the endpoint identifier to be used for the 310 TCP connection (), and to the connection receiver (the 311 secondary) the path to be used to locate the specific TIP 312 transaction manager (). This is all the information required 313 for the connection between the primary and secondary TIP transaction 314 managers to be established. 316 After a connection has been established, the primary party issues an 317 IDENTIFY command. This command includes as parameters two 318 transaction manager URLs: the primary transaction manager URL, and 319 the secondary transaction manager URL. 321 The primary transaction manager URL identifies the TIP transaction 322 manager that initiated the connection. This information is required 323 in certain cases after connection failures, when one of the parties 324 of the connection must re-establish a new connection to the other 325 party in order to complete the two-phase-commit protocol. If the 326 primary party needs to re-establish the connection, the job is easy: 327 a connection is established in the same way as was the original 328 connection. However, if the secondary party needs to re-establish 329 the connection, it must be known how to contact the initiator of the 330 original connection. This information is supplied to the secondary 331 via the primary transaction manager URL on the IDENTIFY command. If 332 a primary transaction manager URL is not supplied, the primary party 333 must not perform any action which would require a connection to be 334 re-established (e.g. to perform recovery actions). 336 The secondary transaction manager URL identifies the receiving TIP 337 transaction manager. In the case of TIP communication via 338 intermediate proxy servers, this URL may be used by the proxy 339 servers to correctly identify and connect to the required TIP 340 transaction manager. 342 8. TIP Uniform Resource Locators 344 Transactions and transaction managers are resources associated with 345 the TIP protocol. Transaction managers and transactions are located 346 using the transaction manager URL scheme. Once a connection has been 347 established, TIP commands may be sent to operate on transactions 348 associated with the respective transaction managers. 350 Applications which want to pull a transaction from a remote node 351 must supply a reference to the remote transaction which allows the 352 local transaction manager (i.e. the transaction manager pulling the 353 transaction) to connect to the remote transaction manager and 354 identify the particular transaction. Applications which want to push 355 a transaction to a remote node must supply a reference to the remote 356 transaction manager (i.e. the transaction manager to which the 357 transaction is to be pushed), which allows the local transaction 358 manager to locate the remote transaction manager. The TIP protocol 359 defines a URL scheme [4] which allows applications and transaction 360 managers to exchange references to transaction managers and 361 transactions. 363 A TIP URL takes the form: 365 TIP://? 367 where identifies the TIP transaction 368 manager (as defined in Section 7 above); and 369 specifies a transaction identifier, which may take one of two forms 370 (standard or non-standard): 372 i. "urn:" ":" 374 A standard transaction identifier, conforming to the proposed 375 Internet Standard for Uniform Resource Names (URNs), as specified 376 by RFC2141; where is the Namespace Identifier, and is 377 the Namespace Specific String. The Namespace ID determines the 378 syntactic interpretation of the Namespace Specific String. The 379 Namespace Specific String is a sequence of characters 380 representing a transaction identifier (as defined by ). The 381 rules for the contents of these fields are specified by [6] 382 (valid characters, encoding, etc.). 384 This format of may be used to express global 385 transaction identifiers in terms of standard representations. 386 Examples for might be or . e.g. 388 TIP://123.123.123.123/?urn:xopen:xid 390 Note that Namespace Ids require registration. See [7] for details 391 on how to do this. 393 ii. 395 A sequence of printable ASCII characters (octets with values in 396 the range 32 through 126 inclusive (excluding ":") representing a 397 transaction identifier. In this non-standard case, it is the 398 combination of and which ensures global uniqueness. e.g. 401 TIP://123.123.123.123/?transid1 403 To create a non-standard TIP URL from a transaction identifier, 404 first replace any reserved characters in the transaction 405 identifier with their equivalent escape sequences, then insert 406 the appropriate transaction manager URL. If the transaction 407 identifier is one that you created, insert your own transaction 408 manager URL. If the transaction identifier is one that you 409 received on a TIP connection that you initiated, use the 410 secondary transaction manager URL that was sent in the IDENTIFY 411 command. If the transaction identifier is one that you received 412 on a TIP connection that you did not initiate, use the primary 413 transaction manager URL that was received in the IDENTIFY 414 command. 416 TIP URLs must be guaranteed globally unique for all time. This 417 uniqueness constraint ensures TIP URLs are never duplicated, thereby 418 preventing possible non-deterministic behaviour. How uniqueness is 419 achieved is implementation specific. For example, the Universally 420 Unique Identifier (UUID, also known as a Globally Unique Identifier, 421 or GUID (see [9])) could be used as part of the . Note also that some standard transaction identifiers may 423 define their own rules for ensuring global uniqueness (e.g. OSI CCR 424 atomic action identifiers). 426 Except as otherwise described above, the TIP URL scheme follows the 427 rules for reserved characters as defined in [4], and uses escape 428 sequences as defined in [4] Section 5. 430 Note that the TIP protocol itself does not use the TIP URL scheme 431 (it does use the transaction manager URL scheme). The TIP URL scheme 432 is proposed as a standard way to pass transaction identification 433 information through other protocols. e.g. between cooperating 434 application processes. The TIP URL may then be used to communicate 435 to the local transaction manager the information necessary to 436 associate the application with a particular TIP transaction. e.g. to 437 PULL the transaction from a remote transaction manager. It is 438 anticipated that each TIP implementation will provide some set of 439 APIs for this purpose ([5] includes examples of such APIs). 441 9. States of a Connection 443 At any instant, only one party on a connection is allowed to send 444 commands, while the other party is only allowed to respond to 445 commands that he receives. Throughout this document, the party that 446 is allowed to send commands is called "primary"; the other party is 447 called "secondary". Initially, the party that initiated the 448 connection is primary; however, a few commands cause the roles to 449 switch. A connection returns to its original polarity whenever the 450 Idle state is reached. 452 When multiplexing is being used, these rules apply independently to 453 each "virtual" connection, regardless of the polarity of the 454 underlying connection (which will be in the Multiplexing state). 456 Note that commands may be sent "out of band" by the secondary via 457 the use of pipelining. This does not affect the polarity of the 458 connection (i.e. the roles of primary and secondary do not switch). 459 See section 12 for details. 461 In the normal case, TIP connections should only be closed by the 462 primary, when in Initial state. It is generally undesirable for a 463 connection to be closed by the secondary, although this may be 464 necessary in certain error cases. 466 At any instant, a connection is in one of the following states. From 467 the point of view of the secondary party, the state changes when he 468 sends a reply; from the point of view of the primary party, the 469 state changes when he receives a reply. 471 Initial: The initial connection starts out in the Initial state. 472 Upon entry into this state, the party that initiated the 473 connection becomes primary, and the other party becomes 474 secondary. There is no transaction associated with the connection 475 in this state. From this state, the primary can send an IDENTIFY 476 or a TLS command. 478 Idle: In this state, the primary and the secondary have agreed on a 479 protocol version, and the primary supplied an identifier to the 480 secondary party to reconnect after a failure. There is no 481 transaction associated with the connection in this state. Upon 482 entry to this state, the party that initiated the connection 483 becomes primary, and the other party becomes secondary. From this 484 state, the primary can send any of the following commands: BEGIN, 485 MULTIPLEX, PUSH, PULL, QUERY and RECONNECT. 487 Begun: In this state, a connection is associated with an active 488 transaction, which can only be completed by a one-phase protocol. 490 A BEGUN response to a BEGIN command places a connection into this 491 state. Failure of a connection in Begun state implies that the 492 transaction will be aborted. From this state, the primary can 493 send an ABORT, or COMMIT command. 495 Enlisted: In this state, the connection is associated with an active 496 transaction, which can be completed by a one-phase or, two-phase 497 protocol. A PUSHED response to a PUSH command, or a PULLED 498 response to a PULL command, places the connection into this 499 state. Failure of the connection in Enlisted state implies that 500 the transaction will be aborted. From this state, the primary can 501 send an ABORT, COMMIT, or PREPARE command. 503 Prepared: In this state, a connection is associated with a 504 transaction that has been prepared. A PREPARED response to a 505 PREPARE command, or a RECONNECTED response to a RECONNECT command 506 places a connection into this state. Unlike other states, 507 failure of a connection in this state does not cause the 508 transaction to automatically abort. From this state, the primary 509 can send an ABORT, or COMMIT command. 511 Multiplexing: In this state, the connection is being used by a 512 multiplexing protocol, which provides its own set of connections. 513 In this state, no TIP commands are possible on the connection. 514 (Of course, TIP commands are possible on the connections supplied 515 by the multiplexing protocol.) The connection can never leave 516 this state. 518 Tls: In this state, the connection is being used by the TLS 519 protocol, which provides its own secured connection. In this 520 state, no TIP commands are possible on the connection. (Of 521 course, TIP commands are possible on the connection supplied by 522 the TLS protocol.) The connection can never leave this state. 524 Error: In this state, a protocol error has occurred, and the 525 connection is no longer useful. The connection can never leave 526 this state. 528 10. Protocol Versioning 530 This document describes version 3 of the protocol. In order to 531 accommodate future versions, the primary party sends a message 532 indicating the lowest and the highest version number it understands. 533 The secondary responds with the highest version number it 534 understands. 536 After such an exchange, communication can occur using the smaller of 537 the highest version numbers (i.e., the highest version number that 538 both understand). This exchange is mandatory and occurs using the 539 IDENTIFY command (and IDENTIFIED response). 541 If the highest version supported by one party is considered obsolete 542 and no longer supported by the other party, no useful communication 543 can occur. In this case, the newer party should merely drop the 544 connection. 546 11. Commands and Responses 548 All commands and responses consist of one line of ASCII text, using 549 only octets with values in the range 32 through 126 inclusive, 550 followed by either a CR (an octet with value 13) or an LR (an octet 551 with value 10). Each line can be split up into one or more "words", 552 where successive words are separated by one or more space octets 553 (value 32). 555 Arbitrary numbers of spaces at the beginning and/or end of each line 556 are allowed, and ignored. 558 Lines that are empty, or consist entirely of spaces are ignored. 559 (One implication of this is that you can terminate lines with both a 560 CR and an LF if desired; the LF will be treated as terminating an 561 empty line, and ignored.) 563 In all cases, the first word of each line indicates the type of 564 command or response; all defined commands and responses consist of 565 upper-case letters only. 567 For some commands and responses, subsequent words convey parameters 568 for the command or response; each command and response takes a fixed 569 number of parameters. 571 All words on a command or response line after (and including) the 572 first undefined word are totally ignored. These can be used to pass 573 human-readable information for debugging or other purposes. 575 12. Command Pipelining 577 In order to reduce communication latency and improve efficiency, it 578 is possible for multiple TIP "lines" (commands or responses) to be 579 pipelined (concatenated) together and sent as a single message. 580 Lines may also be sent "ahead" (by the secondary, for later 581 procesing by the primary). Examples are an ABORT command immediately 582 followed by a BEGIN command, or a COMMITTED response immediately 583 followed by a PULL command. 585 The sending of pipelined lines is an implementation option. Likewise 586 which lines are pipelined together. Generally, it must be certain 587 that the pipelined line will be valid for the state of the 588 connection at the time it is processed by the receiver. It is the 589 responsibility of the sender to determine this. 591 All implementations must support the receipt of pipelined lines - 592 the rules for processing of which are described by the following 593 paragraph: 595 When the connection state is such that a line should be read 596 (either command or response), then that line (when received) is 597 processed. No more lines are read from the connection until 598 processing again reaches such a state. If a line is received on a 599 connection when it is not the turn of the other party to send, 600 that line is _not_ rejected. Instead, the line is held and 601 processed when the connection state again requires it. The 602 receiving party must process lines and issue responses in the 603 order of lines received. If a line causes an error the connection 604 enters the Error state, and all subsequent lines on the 605 connection are discarded. 607 13. TIP Commands 609 Commands pertain either to connections or transactions. Commands 610 which pertain to connections are: IDENTIFY, MULTIPLEX and TLS. 611 Commands which pertain to transactions are: ABORT, BEGIN, COMMIT, 612 PREPARE, PULL, PUSH, QUERY, and RECONNECT. 614 Following is a list of all valid commands, and all possible 615 responses to each: 617 ABORT 619 This command is valid in the Begun, Enlisted, and Prepared 620 states. It informs the secondary that the current transaction of 621 the connection will abort. Possible responses are: 623 ABORTED 624 The transaction has aborted; the connection enters Idle state. 626 ERROR 627 The command was issued in the wrong state, or was malformed. 628 The connection enters the Error state. 630 BEGIN 632 This command is valid only in the Idle state. It asks the 633 secondary to create a new transaction and associate it with the 634 connection. The newly created transaction will be completed with 635 a one-phase protocol. Possible responses are: 637 BEGUN 638 A new transaction has been successfully begun, and that 639 transaction is now the current transaction of the connection. 640 The connection enters Begun state. 642 NOTBEGUN 643 A new transaction could not be begun; the connection remains 644 in Idle state. 646 ERROR 647 The command was issued in the wrong state, or was malformed. 648 The connection enters the Error state. 650 COMMIT 652 This command is valid in the Begun, Enlisted or Prepared states. 653 In the Begun or Enlisted state, it asks the secondary to attempt 654 to commit the transaction; in the Prepared state, it informs the 655 secondary that the transaction has committed. Note that in the 656 Enlisted state this command represents a one-phase protocol, and 657 should only be done when the sender has 1) no local recoverable 658 resources involved in the transaction, and 2) only one 659 subordinate (the sender will not be involved in any transaction 660 recovery process). Possible responses are: 662 ABORTED 663 This response is possible only from the Begun and Enlisted 664 states. It indicates that some party has vetoed the commitment 665 of the transaction, so it has been aborted instead of 666 committing. The connection enters the Idle state. 668 COMMITTED 669 This response indicates that the transaction has been 670 committed, and that the primary no longer has any 671 responsibilities to the secondary with respect to the 672 transaction. The connection enters the Idle state. 674 ERROR 675 The command was issued in the wrong state, or was malformed. 676 The connection enters the Error state. 678 ERROR 680 This command is valid in any state; it informs the secondary that 681 a previous response was not recognized or was badly formed. A 682 secondary should not respond to this command. The connection 683 enters Error state. 685 IDENTIFY 686 687 688 | "-" 690 This command is valid only in the Initial state. The primary 691 party informs the secondary party of: 1) the lowest and highest 692 protocol version supported (all versions between the lowest and 693 highest must be supported; 2) optionally, an identifier for the 694 primary party at which the secondary party can re-establish a 695 connection if ever needed (the primary transaction manager URL); 696 and 3) an identifier which may be used by intermediate proxy 697 servers to connect to the required TIP transaction manager (the 698 secondary transaction manager URL). If a primary transaction 699 manager URL is not supplied, the secondary party will respond 700 with ABORTED or READONLY to any PREPARE commands. Possible 701 responses are: 703 IDENTIFIED 704 The secondary party has been successfully contacted and has 705 saved the primary transaction manager URL. The response 706 contains the highest protocol version supported by the 707 secondary party. All future communication is assumed to take 708 place using the smaller of the protocol versions in the 709 IDENTIFY command and the IDENTIFIED response. The connection 710 enters the Idle state. 712 NEEDTLS 713 The secondary party is only willing to communicate over TLS 714 secured connections. The connection enters the Tls state, and 715 all subsequent communication is as defined by the TLS 716 protocol. This protocol will begin with the first octet after 717 the line terminator of the IDENTIFY command (for data sent by 718 the primary party), and the first byte after the line 719 terminator of the NEEDTLS response (for data sent by the 720 secondary party). This implies that an implementation must not 721 send both a CR and a LF octet after either the IDENTIFY 722 command or the NEEDTLS response, lest the LF octet be mistaken 723 for the first byte of the TLS protocol. The connection 724 provided by the TLS protocol starts out in the Initial state. 725 After TLS has been negotiated, the primary party must resend 726 the IDENTIFY command. If the primary party cannot support (or 727 refuses to use) the TLS protocol, it closes the connection. 729 ERROR 730 The command was issued in the wrong state, or was malformed. 731 This response also occurs if the secondary party does not 732 support any version of the protocol in the range supported by 733 the primary party. The connection enters the Error state. The 734 primary party should close the connection. 736 MULTIPLEX 738 This command is only valid in the Idle state. The command seeks 739 agreement to use the connection for a multiplexing protocol that 740 will supply a large number of connections on the existing 741 connection. The primary suggests a particular multiplexing 742 protocol. The secondary party can either accept or reject use of 743 this protocol. 745 At the present, the only defined protocol identifier is "TMP2.0", 746 which refers to the TIP Multiplexing Protocol, version 2.0. See 747 Appendix A for details of this protocol. Other protocol 748 identifiers may be defined in the future. 750 If the MULTIPLEX command is accepted, the specified multiplexing 751 protocol will totally control the underlying connection. This 752 protocol will begin with the first octet after the line 753 terminator of the MULTIPLEX command (for data sent by the 754 initiator), and the first byte after the line terminator of the 755 MULTIPLEXING response (for data received by the initiator). This 756 implies that an implementation must not send both a CR and a LF 757 octet after either the MULTIPLEX command or the MULTIPLEXING 758 response, lest the LF octet be mistaken for the first byte of the 759 multiplexing protocol. 761 Note that when using TMP V2.0, a single TIP command (TMP 762 application message) must be wholly contained within a single TMP 763 packet (the TMP PUSH flag is not used by TIP). Possible responses 764 to the MULTIPLEX command are: 766 MULTIPLEXING 767 The secondary party agrees to use the specified multiplexing 768 protocol. The connection enters the Multiplexing state, and 769 all subsequent communication is as defined by that protocol. 770 All connections created by the multiplexing protocol start out 771 in the Idle state. 773 CANTMULTIPLEX 774 The secondary party cannot support (or refuses to use) the 775 specified multiplexing protocol. The connection remains in the 776 Idle state. 778 ERROR 779 The command was issued in the wrong state, or was malformed. 780 The connection enters the Error state. 782 PREPARE 784 This command is valid only in the Enlisted state; it requests the 785 secondary to prepare the transaction for commitment (phase one of 786 two-phase commit). Possible responses are: 788 PREPARED 789 The subordinate has prepared the transaction; the connection 790 enters PREPARED state. 792 ABORTED 793 The subordinate has vetoed committing the transaction. The 794 connection enters the Idle state. After this response, the 795 superior has no responsibilities to the subordinate with 796 respect to the transaction. 798 READONLY 799 The subordinate no longer cares whether the transaction 800 commits or aborts. The connection enters the Idle state. After 801 this response, the superior has no responsibilities to the 802 subordinate with respect to the transaction. 804 ERROR 805 The command was issued in the wrong state, or was malformed. 806 The connection enters the Error state. 808 PULL 809 811 This command is only valid in Idle state. This command seeks to 812 establish a superior/subordinate relationship in a transaction, 813 with the primary party of the connection as the subordinate 814 (i.e., he is pulling a transaction from the secondary party). 815 Note that the entire value of (as defined in 816 the section "TIP Uniform Resource Locators") must be specified as 817 the transaction identifier. Possible responses are: 819 PULLED 820 The relationship has been established. Upon receipt of this 821 response, the specified transaction becomes the current 822 transaction of the connection, and the connection enters 823 Enlisted state. Additionally, the roles of primary and 824 secondary become reversed. (That is, the superior becomes the 825 primary for the connection.) 827 NOTPULLED 828 The relationship has not been established (possibly, because 829 the secondary party no longer has the requested transaction). 830 The connection remains in Idle state. 832 ERROR 833 The command was issued in the wrong state, or was malformed. 834 The connection enters the Error state. 836 PUSH 838 This command is valid only in the Idle state. It seeks to 839 establish a superior/subordinate relationship in a transaction 840 with the primary as the superior. Note that the entire value of 841 (as defined in the section "TIP Uniform 842 Resource Locators") must be specified as the transaction 843 identifier. Possible responses are: 845 PUSHED 846 The relationship has been established, and the identifier by 847 which the subordinate knows the transaction is returned. The 848 transaction becomes the current transaction for the 849 connection, and the connection enters Enlisted state. 851 ALREADYPUSHED 852 The relationship has been established, and the identifier by 853 which the subordinate knows the transaction is returned. 854 However, the subordinate already knows about the transaction, 855 and is expecting the two-phase commit protocol to arrive via a 856 different connection. In this case, the connection remains in 857 the Idle state. 859 NOTPUSHED 860 The relationship could not be established. The connection 861 remains in the Idle state. 863 ERROR 864 The command was issued in the wrong state, or was malformed. 865 The connection enters Error state. 867 QUERY 869 This command is valid only in the Idle state. A subordinate uses 870 this command to determine whether a specific transaction still 871 exists at the superior. Possible responses are: 873 QUERIEDEXISTS 874 The transaction still exists. The connection remains in the 875 Idle state. 877 QUERIEDNOTFOUND 878 The transaction no longer exists. The connection remains in 879 the Idle state. 881 ERROR 882 The command was issued in the wrong state, or was malformed. 883 The connection enters Error state. 885 RECONNECT 887 This command is valid only in the Idle state. A superior uses the 888 command to re-establish a connection for a transaction, when the 889 previous connection was lost during Prepared state. Possible 890 responses are: 892 RECONNECTED 893 The subordinate accepts the reconnection. The connection 894 enters Prepared state. 896 NOTRECONNECTED 897 The subordinate no longer knows about the transaction. The 898 connection remains in Idle state. 900 ERROR 901 The command was issued in the wrong state, or was malformed. 902 The connection enters Error state. 904 TLS 906 This command is valid only in the Initial state. A primary uses 907 this command to attempt to establish a secured connection using 908 TLS. 910 If the TLS command is accepted, the TLS protocol will totally 911 control the underlying connection. This protocol will begin with 912 the first octet after the line terminator of the TLS command (for 913 data sent by the primary), and the first byte after the line 914 terminator of the TLSING response (for data received by the 915 primary). This implies that an implementation must not send both 916 a CR and a LF octet after either the TLS command or the TLSING 917 response, lest the LF octet be mistaken for the first byte of the 918 TLS protocol. 920 Possible responses to the TLS command are: 922 TLSING 923 The secondary party agrees to use the TLS protocol[3]. The 924 connection enters the Tls state, and all subsequent 925 communication is as defined by the TLS protocol. The 926 connection provided by the TLS protocol starts out in the 927 Initial state. 929 CANTTLS 930 The secondary party cannot support (or refuses to use) the TLS 931 protocol. The connection remains in the Initial state. 933 ERROR 934 The command was issued in the wrong state, or was malformed. 935 The connection enters the Error state. 937 14. Error Handling 939 If either party receives a line that it cannot understand it closes 940 the connection. If either party (either a command or a response), 941 receives an ERROR indication or an ERROR response on a connection 942 the connection enters the Error state and no further communication 943 is possible on that connection. An implementation may decide to 944 close the connection. Closing of the connection is treated by the 945 other party as a communication failure. 947 Receipt of an ERROR indication or an ERROR response indicates that 948 the other party believes that you have not properly implemented the 949 protocol. 951 15. Connection Failure and Recovery 953 A connection failure may be caused by a communication failure, or by 954 any party closing the connection. It is assumed TIP implementations 955 will use some private mechanism to detect TIP connection failure 956 (e.g. socket keepalive, or a timeout scheme). 958 Depending on the state of a connection, transaction managers will 959 need to take various actions when a connection fails. 961 If the connection fails in Initial or Idle state, the connection 962 does not refer to a transaction. No action is necessary. 964 If the connection fails in the Multiplexing state, all connections 965 provided by the multiplexing protocol are assumed to have failed. 966 Each of them will be treated independently. 968 If the connection fails in Begun or Enlisted state and COMMIT has 969 been sent, then transaction completion has been delegated to the 970 subordinate (the superior is not involved); the outcome of the 971 transaction is unknown by the superior (it is known at the 972 subordinate). The superior uses application-specific means to 973 determine the outcome of the transaction (note that transaction 974 integrity is not compromised in this case since the superior has no 975 recoverable resources involved in the transaction). If the 976 connection fails in Begun or Enlisted state and COMMIT has not been 977 sent, the transaction will be aborted. 979 If the connection fails in Prepared state, then the appropriate 980 action is different for the superior and subordinate in the 981 transaction. 983 If the superior determines that the transaction commits, then it 984 must eventually establish a new connection to the subordinate, and 985 send a RECONNECT command for the transaction. If it receives a 986 NOTRECONNECTED response, it need do nothing else. However, if it 987 receives a RECONNECTED response, it must send a COMMIT request and 988 receive a COMMITTED response. 990 If the superior determines that the transaction aborts, it is 991 allowed to (but not required to) establish a new connection and send 992 a RECONNECT command for the transaction. If it receives a 993 RECONNECTED response, it should send an ABORT command. 995 The above definition allows the superior to reestablish the 996 connection before it knows the outcome of the transaction, if it 997 finds that convenient. Having succeeded in a RECONNECT command, the 998 connection is back in Prepared state, and the superior can send a 999 COMMIT or ABORT command as appropriate when it knows the transaction 1000 outcome. 1002 Note that it is possible for a RECONNECT command to be received by 1003 the subordinate before it is aware that the previous connection has 1004 failed. In this case the subordinate treats the RECONNECT command as 1005 a failure indication and cleans-up any resources associated with the 1006 connection, and associates the transaction state with the new 1007 connection. 1009 If a subordinate notices a connection failure in Prepared state, 1010 then it should periodically attempt to create a new connection to 1011 the superior and send a QUERY command for the transaction. It should 1012 continue doing this until one of the following two events occurs: 1014 1. It receives a QUERIEDNOTFOUND response from the superior. In this 1015 case, the subordinate should abort the transaction. 1017 2. The superior, on some connection that it initiated, sends a 1018 RECONNECT command for the transaction to the subordinate. In this 1019 case, the subordinate can expect to learn the outcome of the 1020 transaction on this new connection. If this new connection should 1021 fail before the subordinate learns the outcome of the 1022 transaction, it should again start sending QUERY commands. 1024 Note that if a TIP system receives either a QUERY or a RECONNECT 1025 command, and for some reason is unable to satisfy the request (e.g. 1026 the necessary recovery information is not currently available), then 1027 the connection should be dropped. 1029 16. Security Considerations 1031 This section is meant to inform application developers, transaction 1032 manager developers, and users of the security implications of TIP as 1033 described by this document. The discussion does not include 1034 definitive solutions to the issues described, though it does make 1035 some suggestions for reducing security risks. 1037 As with all two phase-commit protocols, any security mechanisms 1038 applied to the application communication protocol are liable to be 1039 subverted unless corresponding mechanisms are applied to the 1040 commitment protocol. For example, any authentication between the 1041 parties using the application protocol must be supported by security 1042 of the TIP exchanges to at least the same level of certainty. 1044 16.1. TLS, Mutual Authentication and Authorization 1046 TLS provides optional client-side authentication, optional server- 1047 side authentication, and optional packet encryption. 1049 A TIP implementation may refuse to provide service unless TLS is 1050 being used. It may refuse to provide service if packet encryption is 1051 not being used. It may refuse to provide service unless the remote 1052 party has been authenticated (via TLS). 1054 A TIP implementation should be willing to be authenticated itself 1055 (via TLS). This is true regardless of whether the implementation is 1056 acting as a client or a server. 1058 Once a remote party has been authenticated, a TIP transaction 1059 manager may use that remote party�s identity to decide what 1060 operations to allow. 1062 Whether TLS is to be used on a connection, and if so, how TLS is to 1063 be used, and what operations are to subsequently be allowed, is 1064 determined by the security policies of the connecting TIP 1065 transaction managers towards each other. How these security policies 1066 are defined, and how a TIP transaction manager learns of them is 1067 totally private to the implementation and beyond the scope of this 1068 document. 1070 16.2. PULL-Based Denial-of-Service Attack 1072 Assume that a malicious user knows the identity of a transaction 1073 that is currently active in some transaction manager. If the 1074 malefactor opens a TIP connection to the transaction manager, sends 1075 a PULL command, then closes the connection, he can cause that 1076 transaction to be aborted. This results in a denial of service to 1077 the legitimate owner of the transaction. 1079 An implementation may avoid this attack by refusing PULL commands 1080 unless TLS is being used, the remote party has been authenticated, 1081 and the remote party is trusted. 1083 16.3. PUSH-Based Denial-of-Service Attack 1085 When the connection between two transaction managers is closed while 1086 a transaction is in the Prepared state, each transaction manager 1087 needs to remember information about the transaction until a 1088 connection can be re-established. 1090 If a malicious user exploits this fact to repeatedly create 1091 transactions, get them into Prepared state and drop the connection, 1092 he may cause a transaction manager to suffer resource exhaustion, 1093 thus denying service to all legitimate users of that transaction 1094 manager. 1096 An implementation may avoid this attack by refusing PUSH commands 1097 unless TLS is being used, the remote party has been authenticated, 1098 and the remote party is trusted. 1100 16.4. Transaction Corruption Attack 1102 If a subordinate transaction manager has lost its connection for a 1103 particular prepared transaction, a malicious user can initiate a TIP 1104 connection to the transaction manager, and send it a RECONNECT 1105 command followed by either a COMMIT or an ABORT command for the 1106 transaction. The malicious user could thus cause part of a 1107 transaction to be committed when it should have been aborted, or 1108 vice versa. 1110 An implementation may avoid this attack by recording the 1111 authenticated identity of its superior in a transaction, and by 1112 refusing RECONNECT commands unless TLS is being used and the 1113 authenticated identity of the remote party is the same as the 1114 identity of the original superior. 1116 16.5. Packet-Sniffing Attacks 1118 If a malicious user can intercept traffic on a TIP connection, he 1119 may be able to deduce information useful in planning other attacks. 1120 For example, if comment fields include the product name and version 1121 number of a transaction manager, a malicious user might be able to 1122 use this information to determine what security bugs exist in the 1123 implementation. 1125 An implementation may avoid this attack by always using TLS to 1126 provide session encryption, and by not putting any personalizing 1127 information on the TLS/TLSING command/response pair. 1129 16.6. Man-in-the-Middle Attack 1131 If a malicious user can intercept and alter traffic on a TIP 1132 connection, he can wreak havoc in a number of ways. For example, he 1133 could replace a COMMIT command with an ABORT command. 1135 An implementation may avoid this attack by always using TLS to 1136 provide session encryption and authentication of the remote party. 1138 17. Significant changes from previous version of this Internet-Draft 1140 None (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 [8] Internet-Draft "Uniform Resource Identifiers (URI): Generic 1167 Syntax and Semantics". 1168 T. Berners-Lee et al. 1170 [9] Internet-Draft "UUIDs and GUIDs". 1171 P. J. Leach, R. Salz 1173 19. Authors' Addresses 1175 Jim Lyon Keith Evans 1176 Microsoft Corporation Tandem Computers, Inc. 1177 One Microsoft Way 5425 Stevens Creek Blvd 1178 Redmond, WA 98052-6399, USA Santa Clara, CA 95051-7200, USA 1179 Phone: +1 (206) 936 0867 Phone: +1 (408) 285 5314 1180 Fax: +1 (206) 936 7329 Fax: +1 (408) 285 5245 1181 Email: JimLyon@Microsoft.Com Email: Keith.Evans@Tandem.Com 1182 Johannes Klein 1183 Tandem Computers Inc. 1184 10555 Ridgeview Court 1185 Cupertino, CA 95014-0789, USA 1186 Phone: +1 (408) 285 0453 1187 Fax: +1 (408) 285 9818 1188 Email: Johannes.Klein@Tandem.Com 1190 20. Comments 1192 Please send comments on this document to the authors at 1193 , , 1194 , or to the TIP mailing list at 1195 . You can subscribe to the TIP mailing list by 1196 sending mail to with the line 1197 "subscribe tip " somewhere in the body of the message. 1199 Appendix A. The TIP Multiplexing Protocol Version 2.0. 1201 This appendix describes version 2.0 of the TIP Multiplexing Protocol 1202 (TMP). TMP is intended solely for use with the TIP protocol, and 1203 forms part of the TIP protocol specification (although its 1204 implementation is optional). TMP V2.0 is the only multiplexing 1205 protocol supported by TIP V3.0. 1207 Abstract 1209 TMP provides a simple mechanism for creating multiple lightweight 1210 connections over a single TCP connection. Several such lightweight 1211 connections can be active simultaneously. TMP provides a byte 1212 oriented service, but allows message boundaries to be marked. 1214 A.1. Introduction 1216 There are several protocols in widespread use on the Internet which 1217 create a single TCP connection for each transaction. Unfortunately, 1218 because these transactions are short lived, the cost of setting up 1219 and tearing down these TCP connections becomes significant, both in 1220 terms of resources used and in the delays associated with TCP's 1221 congestion control mechanisms. 1223 The TIP Multiplexing Protocol (TMP) is a simple protocol running on 1224 top of TCP that can be used to create multiple lightweight 1225 connections over a single transport connection. TMP therefore 1226 provides for more efficient use of TCP connections. Data from 1227 several different TMP connections can be interleaved, and both 1228 message boundaries and end of stream markers can be provided. 1230 Because TMP runs on top of a reliable byte ordered transport service 1231 it can avoid most of the extra work TCP must go through in order to 1232 ensure reliability. For example, TMP connections do not need to be 1233 confirmed, so there is no need to wait for handshaking to complete 1234 before data can be sent. 1236 Note: TMP is not intended as a generalized multiplexing protocol. If 1237 you are designing a different protocol that needs multiplexing, TMP 1238 may or may not be appropriate. Protocols with large messages can 1239 exceed the buffering capabilities of the receiver, and under certain 1240 conditions this can cause deadlock. TMP when used with TIP does not 1241 suffer from this problem since TIP is a request-response protocol, 1242 and all messages are short. 1244 A.2. Protocol Model 1246 The basic protocol model is that of multiple lightweight connections 1247 operating over a reliable stream of bytes. The party which initiated 1248 the connection is referred to as the primary, and the party which 1249 accepted the connection is referred to as the secondary. 1251 Connections may be unidirectional or bi-directional; each end of a 1252 bi-directional connection may be closed separately. Connections may 1253 be closed normally, or reset to indicate an abortive release. 1254 Aborting a connection closes both data streams. 1256 Once a connection has been opened, applications can send messages 1257 over it, and signal the end of application level messages. 1258 Application messages are encapsulated in TMP packets and transferred 1259 over the byte stream. A single TIP command (TMP application message) 1260 must be wholly contained within a single TMP packet. 1262 A.3. TMP Packet Format 1264 A TMP packet consists of a 64 bit header followed by zero or more 1265 octets of data. The header contains three fields; a flag byte, the 1266 connection identifier, and the packet length. Both integers, the 1267 connection identifier and the packet length must be sent in network 1268 byte order. 1270 FLAGS 1271 +--------+--------+--------+--------+ 1272 |SFPR0000| Connection ID | 1273 +--------+--------+--------+--------+ 1274 | | Length | 1275 +--------+--------+--------+--------+ 1276 A.3.1. Flag Details 1278 +-------+-----------+-----------------------------------------+ 1279 | Name | Mask | Description | 1280 +-------+-----------+ ----------------------------------------+ 1281 | SYN | 1xxx|0000 | Open a new connection | 1282 | FIN | x1xx|0000 | Close an existing connection | 1283 | PUSH | xx1x|0000 | Mark application level message boundary | 1284 | RESET | xxx1|0000 | Abort the connection | 1285 +-------+-----------+-----------------------------------------+ 1287 A.4. Connection Identifiers 1289 Each TMP connection is identified by a 24 bit integer. TMP 1290 connections created by the party which initiated the underlying TCP 1291 connection must have even identifiers; those created by the other 1292 party must have odd identifiers. 1294 A.5. TMP Connection States 1296 TMP connections can exist in several different states; Closed, 1297 OpenWrite, OpenSynRead, OpenSynReset, OpenReadWrite, CloseWrite, and 1298 CloseRead. A connection can change its state in response to 1299 receiving a packet with the SYN, FIN, or RESET bits set, or in 1300 response to an API call by the application. The available API calls 1301 are open, close, and abort. 1303 The meaning of most states is obvious (e.g. OpenWrite means that a 1304 connection has been opened for writing). The meaning of the states 1305 OpenSynRead and OpenResetRead need more explanation. 1307 In the OpenSynRead state a primary opened and immediately closed the 1308 output data stream of a connection, and is now waiting for a SYN 1309 response from the secondary to open the input data stream for 1310 reading. 1312 In the OpenResetRead state a primary opened and immediately aborted 1313 a connection, and is now waiting for a SYN response from the 1314 secondary to finally close the connection. 1316 A.6. Event Priorities and State Transitions 1318 The state table shown below describes the actions and state 1319 transitions that occur in response to a given event. The events 1320 accepted by each state are listed in priority order with highest 1321 priority first. If multiple events are present in a message, those 1322 events matching the list are processed. If multiple events match, 1323 the event with the highest priority is accepted and processed first. 1324 Any remaining events are processed in the resultant successor state. 1326 For example, if a TMP connection at the secondary is in the Closed 1327 state, and the secondary receives a packet containing a SYN event, a 1328 FIN event and an input data event (i.e. DATA-IN), the secondary 1329 first accepts the SYN event (because it is the only match in Closed 1330 state). The secondary accepts the connection, sends a SYN event and 1331 enters the ReadWrite state. The SYN event is removed from the list 1332 of pending events. The remaining events are FIN and DATA-IN. In the 1333 ReadWrite state the secondary reads the input data (i.e. the DATA-IN 1334 event is processed first because it has higher priority than the FIN 1335 event). Once the data has been read and the DATA-IN event has been 1336 removed from the list of pending events, the FIN event is processed 1337 and the secondary enters the CloseWrite state. 1339 If the secondary receives a packet containing a SYN event, and is 1340 for some reason unable to accept the connection (e.g. insufficient 1341 resources), it should reject the request by sending a SYN event 1342 followed by a RESET event. Note that both events can be sent as part 1343 of the same TMP packet. 1345 If either party receives a TMP packet that it does not understand, 1346 or an event in an incorrect state, it closes the TCP connection. 1348 +==============+=========+==========+==============+ 1349 | Entry State | Event | Action | Exit State | 1350 +==============+=========+==========+==============+ 1351 | Closed | SYN | SYN | ReadWrite | 1352 | | OPEN | SYN | OpenWrite | 1353 +--------------+---------+----------+--------------+ 1354 | OpenWrite | SYN | Accept | ReadWrite | 1355 | | WRITE | DATA-OUT | OpenWrite | 1356 | | CLOSE | FIN | OpenSynRead | 1357 | | ABORT | RESET | OpenSynReset | 1358 +--------------+---------+----------+--------------+ 1359 | OpenSynRead | SYN | Accept | CloseRead | 1360 +--------------+---------+----------+--------------+ 1361 | OpenSynReset | SYN | Accept | Closed | 1362 +--------------+---------+----------+--------------+ 1363 | ReadWrite | DATA-IN | Accept | ReadWrite | 1364 | | FIN | Accept | CloseWrite | 1365 | | RESET | Accept | Closed | 1366 | | WRITE | DATA-OUT | ReadWrite | 1367 | | CLOSE | FIN | CloseRead | 1368 | | ABORT | RESET | Closed | 1369 +--------------+---------+----------+--------------+ 1370 | CloseWrite | RESET | Accept | Closed | 1371 | | WRITE | DATA-OUT | CloseWrite | 1372 | | CLOSE | FIN | Closed | 1373 | | ABORT | RESET | Closed | 1374 +--------------+---------+----------+--------------+ 1375 | CloseRead | DATA-IN | Accept | CloseRead | 1376 | | FIN | Accept | Closed | 1377 | | RESET | Accept | Closed | 1378 | | ABORT | RESET | Closed | 1379 +--------------+---------+----------+--------------+ 1381 TMP Event Priorities and State Transitions