idnits 2.17.1 draft-lyon-itp-nodes-07.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-03-29) 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-06', but the file name used is 'draft-lyon-itp-nodes-07' == 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 1002 has weird spacing: '...ds that conve...' == Line 1201 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 (April 8, 1998) is 9487 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 April 8, 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 view the entire list of current Internet-Drafts, please check 26 the "1id-abstracts.txt" listing contained in the Internet-Drafts 27 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 28 (Northern Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au 29 (Pacific Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu 30 (US West Coast). 32 Abstract 34 In many applications where different nodes cooperate on some work, 35 there is a need to guarantee that the work happens atomically. That 36 is, each node must reach the same conclusion as to whether the work 37 is to be completed, even in the face of failures. This document 38 proposes a simple, easily-implemented protocol for achieving this 39 end. 41 Table of Contents 43 1. Introduction 3 44 2. Example Usage 3 45 3. Transactions 4 46 4. Connections 4 47 5. Transaction Identifiers 5 48 6. Pushing vs. Pulling Transactions 5 49 7. TIP Transaction Manager Identification & Connection Establishment 6 50 8. TIP Uniform Resource Locators 8 51 9. States of a Connection 10 52 10. Protocol Versioning 11 53 11. Commands and Responses 12 54 12. Command Pipelining 12 55 13. TIP Commands 13 56 14. Error Handling 19 57 15. Connection Failure and Recovery 19 58 16. Security Considerations 21 59 17. Significant changes from previous version of this Internet-Draft 23 60 18. References 23 61 19. Authors' Addresses 23 62 20. Comments 24 63 Appendix A. The TIP Multiplexing Protocol Version 2.0. 24 64 1. Introduction 66 The standard method for achieving atomic commitment is the two-phase 67 commit protocol; see [1] for an introduction to atomic commitment 68 and two-phase commit protocols. 70 Numerous two-phase commit protocols have been implemented over the 71 years. However, none of them has become widely used in the 72 Internet, due mainly to their complexity. Most of that complexity 73 comes from the fact that the two-phase commit protocol is bundled 74 together with a specific program-to-program communication protocol, 75 and that protocol lives on top of a very large infrastructure. 77 This memo proposes a very simple two-phase commit protocol. It 78 achieves its simplicity by specifying only how different nodes agree 79 on the outcome of a transaction; it allows (even requires) that the 80 subject matter on which the nodes are agreeing be communicated via 81 other protocols. By doing so, we avoid all of the issues related to 82 application communication semantics and data representation (to name 83 just a few). Independent of the application communication protocol a 84 transaction manager may use the Transport Layer Security protocol 85 [3] to authenticate other transaction managers and encrypt messages. 87 It is envisioned that this protocol will be used mainly for a 88 transaction manager on one Internet node to communicate with a 89 transaction manager on another node. While it is possible to use 90 this protocol for application programs and/or resource managers to 91 speak to transaction managers, this communication is usually intra- 92 node, and most transaction managers already have more-than- adequate 93 interfaces for the task. 95 While we do not expect this protocol to replace existing ones, we do 96 expect that it will be relatively easy for many existing 97 heterogeneous transaction managers to implement this protocol for 98 communication with each other. 100 Further supplemental information regarding the TIP protocol can be 101 found in [5]. 103 2. Example Usage 105 Today the electronic shopping basket is a common metaphor at many 106 electronic store-fronts. Customers browse through an electronic 107 catalog, select goods and place them into an electronic shopping 108 basket. HTTP servers [2] provide various means ranging from URL 109 encoding to context cookies to keep track of client context (e.g. 110 the shopping basket of a customer) and resume it on subsequent 111 customer requests. 113 Once a customer has finished shopping they may decide to commit 114 their selection and place the associated orders. Most orders may 115 have no relationship with each other except being executed as part 116 of the same shopping transaction; others may be dependent on each 117 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 address. 250 [This specification does not prescribe how TIP transaction managers 251 initially obtain the transaction manager address (which will 252 probably be via some implementation-specific configuration 253 mechanism).] 255 TIP transaction manager addresses take the form: 257 259 The component comprises: 261 [:] 263 where is either a or an ; and 264 is a decimal number specifying the port at which the transaction 265 manager (or proxy) is listening for requests to establish TIP 266 connections. If the port number is omitted, the standard TIP port 267 number (3371) is used. 269 A is a standard name, acceptable to the domain name 270 service. It must be sufficiently qualified to be useful to the 271 receiver of the command. 273 An is an IP address, in the usual form: four decimal 274 numbers separated by period characters. 276 The component defines the scope (locale) of the 277 component. 279 The component of the transaction manager address contains 280 data identifying the specific TIP transaction manager, at the 281 location defined by . 283 The component takes the form: 285 "/" [path_segments] 287 path_segments = segment *( "/" segment ) 288 segment = *pchar *( ";" param ) 289 param = *pchar 291 pchar = unreserved | escaped | ":" | "@" | "&" | "=" | "+" 292 unreserved = ASCII character octets with values in the range 293 (inclusive): 48-57, 65-90, 97-122 | "$" | "-" | "_" | 294 "." | "!" | "~" | "*" | "'" | "(" | ")" | "," 295 escaped = "%" hex hex 296 hex = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | 297 "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | 298 "e" | "f" 300 The component may consist of a sequence of path segments 301 separated by a single slash "/" character. Within a path segment, 302 the characters "/", ";", "=", and "?" are reserved. Each path 303 segment may include a sequence of parameters, indicated by the 304 semicolon ";" character. The parameters are not significant to the 305 parsing of relative references. 307 [It is intended that the form of the transaction manager address 308 follow the proposed scheme for Uniform Resource Identifiers (URI) 309 [8].] 311 The TIP transaction manager address therefore provides to the 312 connection initiator (the primary) the endpoint identifier to be 313 used for the TCP connection (), and to the connection 314 receiver (the secondary) the path to be used to locate the 315 specific TIP transaction manager (). This is all the 316 information required for the connection between the primary and 317 secondary TIP transaction managers to be established. 319 After a connection has been established, the primary party issues 320 an IDENTIFY command. This command includes as parameters two 321 transaction manager addresses: the primary transaction manager 322 address, and the secondary transaction manager address. 324 The primary transaction manager address identifies the TIP 325 transaction manager that initiated the connection. This information 326 is required in certain cases after connection failures, when one of 327 the parties of the connection must re-establish a new connection to 328 the other party in order to complete the two-phase-commit protocol. 329 If the primary party needs to re-establish the connection, the job 330 is easy: a connection is established in the same way as was the 331 original connection. However, if the secondary party needs to 332 re-establish the connection, it must be known how to contact the 333 initiator of the original connection. This information is supplied 334 to the secondary via the primary transaction manager address on the 335 IDENTIFY command. If a primary transaction manager address is not 336 supplied, the primary party must not perform any action which would 337 require a connection to be re-established (e.g. to perform recovery 338 actions). 340 The secondary transaction manager address identifies the receiving 341 TIP transaction manager. In the case of TIP communication via 342 intermediate proxy servers, this URL may be used by the proxy 343 servers to correctly identify and connect to the required TIP 344 transaction manager. 346 8. TIP Uniform Resource Locators 348 Transactions and transaction managers are resources associated with 349 the TIP protocol. Transaction managers and transactions are located 350 using the transaction manager address scheme. Once a connection has 351 been established, TIP commands may be sent to operate on 352 transactions associated with the respective transaction managers. 354 Applications which want to pull a transaction from a remote node 355 must supply a reference to the remote transaction which allows the 356 local transaction manager (i.e. the transaction manager pulling the 357 transaction) to connect to the remote transaction manager and 358 identify the particular transaction. Applications which want to push 359 a transaction to a remote node must supply a reference to the remote 360 transaction manager (i.e. the transaction manager to which the 361 transaction is to be pushed), which allows the local transaction 362 manager to locate the remote transaction manager. The TIP protocol 363 defines a URL scheme [4] which allows applications and transaction 364 managers to exchange references to transaction managers and 365 transactions. 367 A TIP URL takes the form: 369 TIP://? 371 where identifies the TIP transaction 372 manager (as defined in Section 7 above); and 373 specifies a transaction identifier, which may take one of two forms 374 (standard or non-standard): 376 i. "urn:" ":" 378 A standard transaction identifier, conforming to the proposed 379 Internet Standard for Uniform Resource Names (URNs), as specified 380 by RFC2141; where is the Namespace Identifier, and is 381 the Namespace Specific String. The Namespace ID determines the 382 syntactic interpretation of the Namespace Specific String. The 383 Namespace Specific String is a sequence of characters 384 representing a transaction identifier (as defined by ). The 385 rules for the contents of these fields are specified by [6] 386 (valid characters, encoding, etc.). 388 This format of may be used to express global 389 transaction identifiers in terms of standard representations. 390 Examples for might be or . e.g. 392 TIP://123.123.123.123/?urn:xopen:xid 394 Note that Namespace Ids require registration. See [7] for details 395 on how to do this. 397 ii. 399 A sequence of printable ASCII characters (octets with values in 400 the range 32 through 126 inclusive (excluding ":") representing a 401 transaction identifier. In this non-standard case, it is the 402 combination of and which ensures global uniqueness. e.g. 405 TIP://123.123.123.123/?transid1 407 To create a non-standard TIP URL from a transaction identifier, 408 first replace any reserved characters in the transaction 409 identifier with their equivalent escape sequences, then insert 410 the appropriate transaction manager address. If the transaction 411 identifier is one that you created, insert your own transaction 412 manager address. If the transaction identifier is one that you 413 received on a TIP connection that you initiated, use the 414 secondary transaction manager address that was sent in the 415 IDENTIFY command. If the transaction identifier is one that you 416 received on a TIP connection that you did not initiate, use the 417 primary transaction manager address that was received in the 418 IDENTIFY command. 420 TIP URLs must be guaranteed globally unique for all time. This 421 uniqueness constraint ensures TIP URLs are never duplicated, thereby 422 preventing possible non-deterministic behaviour. How uniqueness is 423 achieved is implementation specific. For example, the Universally 424 Unique Identifier (UUID, also known as a Globally Unique Identifier, 425 or GUID (see [9])) could be used as part of the . Note also that some standard transaction identifiers may 427 define their own rules for ensuring global uniqueness (e.g. OSI CCR 428 atomic action identifiers). 430 Except as otherwise described above, the TIP URL scheme follows the 431 rules for reserved characters as defined in [4], and uses escape 432 sequences as defined in [4] Section 5. 434 Note that the TIP protocol itself does not use the TIP URL scheme 435 (it does use the transaction manager address scheme). The TIP URL 436 scheme is proposed as a standard way to pass transaction 437 identification information through other protocols. e.g. between 438 cooperating application processes. The TIP URL may then be used to 439 communicate to the local transaction manager the information 440 necessary to associate the application with a particular TIP 441 transaction. e.g. to PULL the transaction from a remote transaction 442 manager. It is anticipated that each TIP implementation will provide 443 some set of APIs for this purpose ([5] includes examples of such 444 APIs). 446 9. States of a Connection 448 At any instant, only one party on a connection is allowed to send 449 commands, while the other party is only allowed to respond to 450 commands that he receives. Throughout this document, the party that 451 is allowed to send commands is called "primary"; the other party is 452 called "secondary". Initially, the party that initiated the 453 connection is primary; however, a few commands cause the roles to 454 switch. A connection returns to its original polarity whenever the 455 Idle state is reached. 457 When multiplexing is being used, these rules apply independently to 458 each "virtual" connection, regardless of the polarity of the 459 underlying connection (which will be in the Multiplexing state). 461 Note that commands may be sent "out of band" by the secondary via 462 the use of pipelining. This does not affect the polarity of the 463 connection (i.e. the roles of primary and secondary do not switch). 464 See section 12 for details. 466 In the normal case, TIP connections should only be closed by the 467 primary, when in Initial state. It is generally undesirable for a 468 connection to be closed by the secondary, although this may be 469 necessary in certain error cases. 471 At any instant, a connection is in one of the following states. From 472 the point of view of the secondary party, the state changes when he 473 sends a reply; from the point of view of the primary party, the 474 state changes when he receives a reply. 476 Initial: The initial connection starts out in the Initial state. 477 Upon entry into this state, the party that initiated the 478 connection becomes primary, and the other party becomes 479 secondary. There is no transaction associated with the connection 480 in this state. From this state, the primary can send an IDENTIFY 481 or a TLS command. 483 Idle: In this state, the primary and the secondary have agreed on a 484 protocol version, and the primary supplied an identifier to the 485 secondary party to reconnect after a failure. There is no 486 transaction associated with the connection in this state. Upon 487 entry to this state, the party that initiated the connection 488 becomes primary, and the other party becomes secondary. From this 489 state, the primary can send any of the following commands: BEGIN, 490 MULTIPLEX, PUSH, PULL, QUERY and RECONNECT. 492 Begun: In this state, a connection is associated with an active 493 transaction, which can only be completed by a one-phase protocol. 495 A BEGUN response to a BEGIN command places a connection into this 496 state. Failure of a connection in Begun state implies that the 497 transaction will be aborted. From this state, the primary can 498 send an ABORT, or COMMIT command. 500 Enlisted: In this state, the connection is associated with an active 501 transaction, which can be completed by a one-phase or, two-phase 502 protocol. A PUSHED response to a PUSH command, or a PULLED 503 response to a PULL command, places the connection into this 504 state. Failure of the connection in Enlisted state implies that 505 the transaction will be aborted. From this state, the primary can 506 send an ABORT, COMMIT, or PREPARE command. 508 Prepared: In this state, a connection is associated with a 509 transaction that has been prepared. A PREPARED response to a 510 PREPARE command, or a RECONNECTED response to a RECONNECT command 511 places a connection into this state. Unlike other states, 512 failure of a connection in this state does not cause the 513 transaction to automatically abort. From this state, the primary 514 can send an ABORT, or COMMIT command. 516 Multiplexing: In this state, the connection is being used by a 517 multiplexing protocol, which provides its own set of connections. 518 In this state, no TIP commands are possible on the connection. 519 (Of course, TIP commands are possible on the connections supplied 520 by the multiplexing protocol.) The connection can never leave 521 this state. 523 Tls: In this state, the connection is being used by the TLS 524 protocol, which provides its own secured connection. In this 525 state, no TIP commands are possible on the connection. (Of 526 course, TIP commands are possible on the connection supplied by 527 the TLS protocol.) The connection can never leave this state. 529 Error: In this state, a protocol error has occurred, and the 530 connection is no longer useful. The connection can never leave 531 this state. 533 10. Protocol Versioning 535 This document describes version 3 of the protocol. In order to 536 accommodate future versions, the primary party sends a message 537 indicating the lowest and the highest version number it understands. 538 The secondary responds with the highest version number it 539 understands. 541 After such an exchange, communication can occur using the smaller of 542 the highest version numbers (i.e., the highest version number that 543 both understand). This exchange is mandatory and occurs using the 544 IDENTIFY command (and IDENTIFIED response). 546 If the highest version supported by one party is considered obsolete 547 and no longer supported by the other party, no useful communication 548 can occur. In this case, the newer party should merely drop the 549 connection. 551 11. Commands and Responses 553 All commands and responses consist of one line of ASCII text, using 554 only octets with values in the range 32 through 126 inclusive, 555 followed by either a CR (an octet with value 13) or an LR (an octet 556 with value 10). Each line can be split up into one or more "words", 557 where successive words are separated by one or more space octets 558 (value 32). 560 Arbitrary numbers of spaces at the beginning and/or end of each line 561 are allowed, and ignored. 563 Lines that are empty, or consist entirely of spaces are ignored. 564 (One implication of this is that you can terminate lines with both a 565 CR and an LF if desired; the LF will be treated as terminating an 566 empty line, and ignored.) 568 In all cases, the first word of each line indicates the type of 569 command or response; all defined commands and responses consist of 570 upper-case letters only. 572 For some commands and responses, subsequent words convey parameters 573 for the command or response; each command and response takes a fixed 574 number of parameters. 576 All words on a command or response line after (and including) the 577 first undefined word are totally ignored. These can be used to pass 578 human-readable information for debugging or other purposes. 580 12. Command Pipelining 582 In order to reduce communication latency and improve efficiency, it 583 is possible for multiple TIP "lines" (commands or responses) to be 584 pipelined (concatenated) together and sent as a single message. 585 Lines may also be sent "ahead" (by the secondary, for later 586 procesing by the primary). Examples are an ABORT command immediately 587 followed by a BEGIN command, or a COMMITTED response immediately 588 followed by a PULL command. 590 The sending of pipelined lines is an implementation option. Likewise 591 which lines are pipelined together. Generally, it must be certain 592 that the pipelined line will be valid for the state of the 593 connection at the time it is processed by the receiver. It is the 594 responsibility of the sender to determine this. 596 All implementations must support the receipt of pipelined lines - 597 the rules for processing of which are described by the following 598 paragraph: 600 When the connection state is such that a line should be read 601 (either command or response), then that line (when received) is 602 processed. No more lines are read from the connection until 603 processing again reaches such a state. If a line is received on a 604 connection when it is not the turn of the other party to send, 605 that line is _not_ rejected. Instead, the line is held and 606 processed when the connection state again requires it. The 607 receiving party must process lines and issue responses in the 608 order of lines received. If a line causes an error the connection 609 enters the Error state, and all subsequent lines on the 610 connection are discarded. 612 13. TIP Commands 614 Commands pertain either to connections or transactions. Commands 615 which pertain to connections are: IDENTIFY, MULTIPLEX and TLS. 616 Commands which pertain to transactions are: ABORT, BEGIN, COMMIT, 617 PREPARE, PULL, PUSH, QUERY, and RECONNECT. 619 Following is a list of all valid commands, and all possible 620 responses to each: 622 ABORT 624 This command is valid in the Begun, Enlisted, and Prepared 625 states. It informs the secondary that the current transaction of 626 the connection will abort. Possible responses are: 628 ABORTED 629 The transaction has aborted; the connection enters Idle state. 631 ERROR 632 The command was issued in the wrong state, or was malformed. 633 The connection enters the Error state. 635 BEGIN 637 This command is valid only in the Idle state. It asks the 638 secondary to create a new transaction and associate it with the 639 connection. The newly created transaction will be completed with 640 a one-phase protocol. Possible responses are: 642 BEGUN 643 A new transaction has been successfully begun, and that 644 transaction is now the current transaction of the connection. 645 The connection enters Begun state. 647 NOTBEGUN 648 A new transaction could not be begun; the connection remains 649 in Idle state. 651 ERROR 652 The command was issued in the wrong state, or was malformed. 653 The connection enters the Error state. 655 COMMIT 657 This command is valid in the Begun, Enlisted or Prepared states. 658 In the Begun or Enlisted state, it asks the secondary to attempt 659 to commit the transaction; in the Prepared state, it informs the 660 secondary that the transaction has committed. Note that in the 661 Enlisted state this command represents a one-phase protocol, and 662 should only be done when the sender has 1) no local recoverable 663 resources involved in the transaction, and 2) only one 664 subordinate (the sender will not be involved in any transaction 665 recovery process). Possible responses are: 667 ABORTED 668 This response is possible only from the Begun and Enlisted 669 states. It indicates that some party has vetoed the commitment 670 of the transaction, so it has been aborted instead of 671 committing. The connection enters the Idle state. 673 COMMITTED 674 This response indicates that the transaction has been 675 committed, and that the primary no longer has any 676 responsibilities to the secondary with respect to the 677 transaction. The connection enters the Idle state. 679 ERROR 680 The command was issued in the wrong state, or was malformed. 681 The connection enters the Error state. 683 ERROR 685 This command is valid in any state; it informs the secondary that 686 a previous response was not recognized or was badly formed. A 687 secondary should not respond to this command. The connection 688 enters Error state. 690 IDENTIFY 691 692 | "-" 693 695 This command is valid only in the Initial state. The primary 696 party informs the secondary party of: 1) the lowest and highest 697 protocol version supported (all versions between the lowest and 698 highest must be supported; 2) optionally, an identifier for the 699 primary party at which the secondary party can re-establish a 700 connection if ever needed (the primary transaction manager 701 address); and 3) an identifier which may be used by intermediate 702 proxy servers to connect to the required TIP transaction manager 703 (the secondary transaction manager address). If a primary 704 transaction manager address is not supplied, the secondary party 705 will respond with ABORTED or READONLY to any PREPARE commands. 706 Possible responses are: 708 IDENTIFIED 709 The secondary party has been successfully contacted and has 710 saved the primary transaction manager address. The response 711 contains the highest protocol version supported by the 712 secondary party. All future communication is assumed to take 713 place using the smaller of the protocol versions in the 714 IDENTIFY command and the IDENTIFIED response. The connection 715 enters the Idle state. 717 NEEDTLS 718 The secondary party is only willing to communicate over TLS 719 secured connections. The connection enters the Tls state, and 720 all subsequent communication is as defined by the TLS 721 protocol. This protocol will begin with the first octet after 722 the line terminator of the IDENTIFY command (for data sent by 723 the primary party), and the first byte after the line 724 terminator of the NEEDTLS response (for data sent by the 725 secondary party). This implies that an implementation must not 726 send both a CR and a LF octet after either the IDENTIFY 727 command or the NEEDTLS response, lest the LF octet be mistaken 728 for the first byte of the TLS protocol. The connection 729 provided by the TLS protocol starts out in the Initial state. 730 After TLS has been negotiated, the primary party must resend 731 the IDENTIFY command. If the primary party cannot support (or 732 refuses to use) the TLS protocol, it closes the connection. 734 ERROR 735 The command was issued in the wrong state, or was malformed. 736 This response also occurs if the secondary party does not 737 support any version of the protocol in the range supported by 738 the primary party. The connection enters the Error state. The 739 primary party should close the connection. 741 MULTIPLEX 743 This command is only valid in the Idle state. The command seeks 744 agreement to use the connection for a multiplexing protocol that 745 will supply a large number of connections on the existing 746 connection. The primary suggests a particular multiplexing 747 protocol. The secondary party can either accept or reject use of 748 this protocol. 750 At the present, the only defined protocol identifier is "TMP2.0", 751 which refers to the TIP Multiplexing Protocol, version 2.0. See 752 Appendix A for details of this protocol. Other protocol 753 identifiers may be defined in the future. 755 If the MULTIPLEX command is accepted, the specified multiplexing 756 protocol will totally control the underlying connection. This 757 protocol will begin with the first octet after the line 758 terminator of the MULTIPLEX command (for data sent by the 759 initiator), and the first byte after the line terminator of the 760 MULTIPLEXING response (for data received by the initiator). This 761 implies that an implementation must not send both a CR and a LF 762 octet after either the MULTIPLEX command or the MULTIPLEXING 763 response, lest the LF octet be mistaken for the first byte of the 764 multiplexing protocol. 766 Note that when using TMP V2.0, a single TIP command (TMP 767 application message) must be wholly contained within a single TMP 768 packet (the TMP PUSH flag is not used by TIP). Possible responses 769 to the MULTIPLEX command are: 771 MULTIPLEXING 772 The secondary party agrees to use the specified multiplexing 773 protocol. The connection enters the Multiplexing state, and 774 all subsequent communication is as defined by that protocol. 775 All connections created by the multiplexing protocol start out 776 in the Idle state. 778 CANTMULTIPLEX 779 The secondary party cannot support (or refuses to use) the 780 specified multiplexing protocol. The connection remains in the 781 Idle state. 783 ERROR 784 The command was issued in the wrong state, or was malformed. 785 The connection enters the Error state. 787 PREPARE 789 This command is valid only in the Enlisted state; it requests the 790 secondary to prepare the transaction for commitment (phase one of 791 two-phase commit). Possible responses are: 793 PREPARED 794 The subordinate has prepared the transaction; the connection 795 enters PREPARED state. 797 ABORTED 798 The subordinate has vetoed committing the transaction. The 799 connection enters the Idle state. After this response, the 800 superior has no responsibilities to the subordinate with 801 respect to the transaction. 803 READONLY 804 The subordinate no longer cares whether the transaction 805 commits or aborts. The connection enters the Idle state. After 806 this response, the superior has no responsibilities to the 807 subordinate with respect to the transaction. 809 ERROR 810 The command was issued in the wrong state, or was malformed. 811 The connection enters the Error state. 813 PULL 814 816 This command is only valid in Idle state. This command seeks to 817 establish a superior/subordinate relationship in a transaction, 818 with the primary party of the connection as the subordinate 819 (i.e., he is pulling a transaction from the secondary party). 820 Note that the entire value of (as defined in 821 the section "TIP Uniform Resource Locators") must be specified as 822 the transaction identifier. Possible responses are: 824 PULLED 825 The relationship has been established. Upon receipt of this 826 response, the specified transaction becomes the current 827 transaction of the connection, and the connection enters 828 Enlisted state. Additionally, the roles of primary and 829 secondary become reversed. (That is, the superior becomes the 830 primary for the connection.) 832 NOTPULLED 833 The relationship has not been established (possibly, because 834 the secondary party no longer has the requested transaction). 835 The connection remains in Idle state. 837 ERROR 838 The command was issued in the wrong state, or was malformed. 839 The connection enters the Error state. 841 PUSH 843 This command is valid only in the Idle state. It seeks to 844 establish a superior/subordinate relationship in a transaction 845 with the primary as the superior. Note that the entire value of 846 (as defined in the section "TIP Uniform 847 Resource Locators") must be specified as the transaction 848 identifier. Possible responses are: 850 PUSHED 851 The relationship has been established, and the identifier by 852 which the subordinate knows the transaction is returned. The 853 transaction becomes the current transaction for the 854 connection, and the connection enters Enlisted state. 856 ALREADYPUSHED 857 The relationship has been established, and the identifier by 858 which the subordinate knows the transaction is returned. 859 However, the subordinate already knows about the transaction, 860 and is expecting the two-phase commit protocol to arrive via a 861 different connection. In this case, the connection remains in 862 the Idle state. 864 NOTPUSHED 865 The relationship could not be established. The connection 866 remains in the Idle state. 868 ERROR 869 The command was issued in the wrong state, or was malformed. 870 The connection enters Error state. 872 QUERY 874 This command is valid only in the Idle state. A subordinate uses 875 this command to determine whether a specific transaction still 876 exists at the superior. Possible responses are: 878 QUERIEDEXISTS 879 The transaction still exists. The connection remains in the 880 Idle state. 882 QUERIEDNOTFOUND 883 The transaction no longer exists. The connection remains in 884 the Idle state. 886 ERROR 887 The command was issued in the wrong state, or was malformed. 888 The connection enters Error state. 890 RECONNECT 892 This command is valid only in the Idle state. A superior uses the 893 command to re-establish a connection for a transaction, when the 894 previous connection was lost during Prepared state. Possible 895 responses are: 897 RECONNECTED 898 The subordinate accepts the reconnection. The connection 899 enters Prepared state. 901 NOTRECONNECTED 902 The subordinate no longer knows about the transaction. The 903 connection remains in Idle state. 905 ERROR 906 The command was issued in the wrong state, or was malformed. 907 The connection enters Error state. 909 TLS 911 This command is valid only in the Initial state. A primary uses 912 this command to attempt to establish a secured connection using 913 TLS. 915 If the TLS command is accepted, the TLS protocol will totally 916 control the underlying connection. This protocol will begin with 917 the first octet after the line terminator of the TLS command (for 918 data sent by the primary), and the first byte after the line 919 terminator of the TLSING response (for data received by the 920 primary). This implies that an implementation must not send both 921 a CR and a LF octet after either the TLS command or the TLSING 922 response, lest the LF octet be mistaken for the first byte of the 923 TLS protocol. 925 Possible responses to the TLS command are: 927 TLSING 928 The secondary party agrees to use the TLS protocol[3]. The 929 connection enters the Tls state, and all subsequent 930 communication is as defined by the TLS protocol. The 931 connection provided by the TLS protocol starts out in the 932 Initial state. 934 CANTTLS 935 The secondary party cannot support (or refuses to use) the TLS 936 protocol. The connection remains in the Initial state. 938 ERROR 939 The command was issued in the wrong state, or was malformed. 940 The connection enters the Error state. 942 14. Error Handling 944 If either party receives a line that it cannot understand it closes 945 the connection. If either party (either a command or a response), 946 receives an ERROR indication or an ERROR response on a connection 947 the connection enters the Error state and no further communication 948 is possible on that connection. An implementation may decide to 949 close the connection. Closing of the connection is treated by the 950 other party as a communication failure. 952 Receipt of an ERROR indication or an ERROR response indicates that 953 the other party believes that you have not properly implemented the 954 protocol. 956 15. Connection Failure and Recovery 958 A connection failure may be caused by a communication failure, or by 959 any party closing the connection. It is assumed TIP implementations 960 will use some private mechanism to detect TIP connection failure 961 (e.g. socket keepalive, or a timeout scheme). 963 Depending on the state of a connection, transaction managers will 964 need to take various actions when a connection fails. 966 If the connection fails in Initial or Idle state, the connection 967 does not refer to a transaction. No action is necessary. 969 If the connection fails in the Multiplexing state, all connections 970 provided by the multiplexing protocol are assumed to have failed. 971 Each of them will be treated independently. 973 If the connection fails in Begun or Enlisted state and COMMIT has 974 been sent, then transaction completion has been delegated to the 975 subordinate (the superior is not involved); the outcome of the 976 transaction is unknown by the superior (it is known at the 977 subordinate). The superior uses application-specific means to 978 determine the outcome of the transaction (note that transaction 979 integrity is not compromised in this case since the superior has no 980 recoverable resources involved in the transaction). If the 981 connection fails in Begun or Enlisted state and COMMIT has not been 982 sent, the transaction will be aborted. 984 If the connection fails in Prepared state, then the appropriate 985 action is different for the superior and subordinate in the 986 transaction. 988 If the superior determines that the transaction commits, then it 989 must eventually establish a new connection to the subordinate, and 990 send a RECONNECT command for the transaction. If it receives a 991 NOTRECONNECTED response, it need do nothing else. However, if it 992 receives a RECONNECTED response, it must send a COMMIT request and 993 receive a COMMITTED response. 995 If the superior determines that the transaction aborts, it is 996 allowed to (but not required to) establish a new connection and send 997 a RECONNECT command for the transaction. If it receives a 998 RECONNECTED response, it should send an ABORT command. 1000 The above definition allows the superior to reestablish the 1001 connection before it knows the outcome of the transaction, if it 1002 finds that convenient. Having succeeded in a RECONNECT command, the 1003 connection is back in Prepared state, and the superior can send a 1004 COMMIT or ABORT command as appropriate when it knows the transaction 1005 outcome. 1007 Note that it is possible for a RECONNECT command to be received by 1008 the subordinate before it is aware that the previous connection has 1009 failed. In this case the subordinate treats the RECONNECT command as 1010 a failure indication and cleans-up any resources associated with the 1011 connection, and associates the transaction state with the new 1012 connection. 1014 If a subordinate notices a connection failure in Prepared state, 1015 then it should periodically attempt to create a new connection to 1016 the superior and send a QUERY command for the transaction. It should 1017 continue doing this until one of the following two events occurs: 1019 1. It receives a QUERIEDNOTFOUND response from the superior. In this 1020 case, the subordinate should abort the transaction. 1022 2. The superior, on some connection that it initiated, sends a 1023 RECONNECT command for the transaction to the subordinate. In this 1024 case, the subordinate can expect to learn the outcome of the 1025 transaction on this new connection. If this new connection should 1026 fail before the subordinate learns the outcome of the 1027 transaction, it should again start sending QUERY commands. 1029 Note that if a TIP system receives either a QUERY or a RECONNECT 1030 command, and for some reason is unable to satisfy the request (e.g. 1031 the necessary recovery information is not currently available), then 1032 the connection should be dropped. 1034 16. Security Considerations 1036 This section is meant to inform application developers, transaction 1037 manager developers, and users of the security implications of TIP as 1038 described by this document. The discussion does not include 1039 definitive solutions to the issues described, though it does make 1040 some suggestions for reducing security risks. 1042 As with all two phase-commit protocols, any security mechanisms 1043 applied to the application communication protocol are liable to be 1044 subverted unless corresponding mechanisms are applied to the 1045 commitment protocol. For example, any authentication between the 1046 parties using the application protocol must be supported by security 1047 of the TIP exchanges to at least the same level of certainty. 1049 16.1. TLS, Mutual Authentication and Authorization 1051 TLS provides optional client-side authentication, optional server- 1052 side authentication, and optional packet encryption. 1054 A TIP implementation may refuse to provide service unless TLS is 1055 being used. It may refuse to provide service if packet encryption is 1056 not being used. It may refuse to provide service unless the remote 1057 party has been authenticated (via TLS). 1059 A TIP implementation should be willing to be authenticated itself 1060 (via TLS). This is true regardless of whether the implementation is 1061 acting as a client or a server. 1063 Once a remote party has been authenticated, a TIP transaction 1064 manager may use that remote party�s identity to decide what 1065 operations to allow. 1067 Whether TLS is to be used on a connection, and if so, how TLS is to 1068 be used, and what operations are to subsequently be allowed, is 1069 determined by the security policies of the connecting TIP 1070 transaction managers towards each other. How these security policies 1071 are defined, and how a TIP transaction manager learns of them is 1072 totally private to the implementation and beyond the scope of this 1073 document. 1075 16.2. PULL-Based Denial-of-Service Attack 1077 Assume that a malicious user knows the identity of a transaction 1078 that is currently active in some transaction manager. If the 1079 malefactor opens a TIP connection to the transaction manager, sends 1080 a PULL command, then closes the connection, he can cause that 1081 transaction to be aborted. This results in a denial of service to 1082 the legitimate owner of the transaction. 1084 An implementation may avoid this attack by refusing PULL commands 1085 unless TLS is being used, the remote party has been authenticated, 1086 and the remote party is trusted. 1088 16.3. PUSH-Based Denial-of-Service Attack 1090 When the connection between two transaction managers is closed while 1091 a transaction is in the Prepared state, each transaction manager 1092 needs to remember information about the transaction until a 1093 connection can be re-established. 1095 If a malicious user exploits this fact to repeatedly create 1096 transactions, get them into Prepared state and drop the connection, 1097 he may cause a transaction manager to suffer resource exhaustion, 1098 thus denying service to all legitimate users of that transaction 1099 manager. 1101 An implementation may avoid this attack by refusing PUSH commands 1102 unless TLS is being used, the remote party has been authenticated, 1103 and the remote party is trusted. 1105 16.4. Transaction Corruption Attack 1107 If a subordinate transaction manager has lost its connection for a 1108 particular prepared transaction, a malicious user can initiate a TIP 1109 connection to the transaction manager, and send it a RECONNECT 1110 command followed by either a COMMIT or an ABORT command for the 1111 transaction. The malicious user could thus cause part of a 1112 transaction to be committed when it should have been aborted, or 1113 vice versa. 1115 An implementation may avoid this attack by recording the 1116 authenticated identity of its superior in a transaction, and by 1117 refusing RECONNECT commands unless TLS is being used and the 1118 authenticated identity of the remote party is the same as the 1119 identity of the original superior. 1121 16.5. Packet-Sniffing Attacks 1123 If a malicious user can intercept traffic on a TIP connection, he 1124 may be able to deduce information useful in planning other attacks. 1125 For example, if comment fields include the product name and version 1126 number of a transaction manager, a malicious user might be able to 1127 use this information to determine what security bugs exist in the 1128 implementation. 1130 An implementation may avoid this attack by always using TLS to 1131 provide session encryption, and by not putting any personalizing 1132 information on the TLS/TLSING command/response pair. 1134 16.6. Man-in-the-Middle Attack 1136 If a malicious user can intercept and alter traffic on a TIP 1137 connection, he can wreak havoc in a number of ways. For example, he 1138 could replace a COMMIT command with an ABORT command. 1140 An implementation may avoid this attack by always using TLS to 1141 provide session encryption and authentication of the remote party. 1143 17. Significant changes from previous version of this Internet-Draft 1145 None (minor editing). 1147 18. References 1149 [1] Gray, J. and A. Reuter (1993), Transaction Processing: Concepts 1150 and Techniques. San Francisco, CA: Morgan Kaufmann Publishers. 1151 (ISBN 1-55860-190-2). 1153 [2] RFC2068 Standards Track "Hypertext Transfer Protocol -- 1154 HTTP/1.1". 1155 R. Fielding et al. 1157 [3] Internet-Draft "The TLS Protocol Version 1.0". T. Dierks et al. 1159 [4] RFC1738 Standards Track "Uniform Resource Locators (URL)". 1160 T. Berners-Lee et al. 1162 [5] Internet-Draft "Transaction Internet Protocol - Requirements 1163 and Supplemental Information". K. Evans et al. 1165 [6] RFC2141 "URN Syntax". R. Moats. 1167 [7] Internet-Draft "Namespace Identifier Requirements for URN 1168 Services". 1169 P. Faltstrom et al. 1171 [8] Internet-Draft "Uniform Resource Identifiers (URI): Generic 1172 Syntax and Semantics". 1173 T. Berners-Lee et al. 1175 [9] Internet-Draft "UUIDs and GUIDs". 1176 P. J. Leach, R. Salz 1178 19. Authors' Addresses 1180 Jim Lyon Keith Evans 1181 Microsoft Corporation Tandem Computers, Inc. 1182 One Microsoft Way 5425 Stevens Creek Blvd 1183 Redmond, WA 98052-6399, USA Santa Clara, CA 95051-7200, USA 1184 Phone: +1 (206) 936 0867 Phone: +1 (408) 285 5314 1185 Fax: +1 (206) 936 7329 Fax: +1 (408) 285 5245 1186 Email: JimLyon@Microsoft.Com Email: Keith.Evans@Tandem.Com 1187 Johannes Klein 1188 Tandem Computers Inc. 1189 10555 Ridgeview Court 1190 Cupertino, CA 95014-0789, USA 1191 Phone: +1 (408) 285 0453 1192 Fax: +1 (408) 285 9818 1193 Email: Johannes.Klein@Tandem.Com 1195 20. Comments 1197 Please send comments on this document to the authors at 1198 , , 1199 , or to the TIP mailing list at 1200 . You can subscribe to the TIP mailing list by 1201 sending mail to with the line 1202 "subscribe tip " somewhere in the body of the message. 1204 Appendix A. The TIP Multiplexing Protocol Version 2.0. 1206 This appendix describes version 2.0 of the TIP Multiplexing Protocol 1207 (TMP). TMP is intended solely for use with the TIP protocol, and 1208 forms part of the TIP protocol specification (although its 1209 implementation is optional). TMP V2.0 is the only multiplexing 1210 protocol supported by TIP V3.0. 1212 Abstract 1214 TMP provides a simple mechanism for creating multiple lightweight 1215 connections over a single TCP connection. Several such lightweight 1216 connections can be active simultaneously. TMP provides a byte 1217 oriented service, but allows message boundaries to be marked. 1219 A.1. Introduction 1221 There are several protocols in widespread use on the Internet which 1222 create a single TCP connection for each transaction. Unfortunately, 1223 because these transactions are short lived, the cost of setting up 1224 and tearing down these TCP connections becomes significant, both in 1225 terms of resources used and in the delays associated with TCP's 1226 congestion control mechanisms. 1228 The TIP Multiplexing Protocol (TMP) is a simple protocol running on 1229 top of TCP that can be used to create multiple lightweight 1230 connections over a single transport connection. TMP therefore 1231 provides for more efficient use of TCP connections. Data from 1232 several different TMP connections can be interleaved, and both 1233 message boundaries and end of stream markers can be provided. 1235 Because TMP runs on top of a reliable byte ordered transport service 1236 it can avoid most of the extra work TCP must go through in order to 1237 ensure reliability. For example, TMP connections do not need to be 1238 confirmed, so there is no need to wait for handshaking to complete 1239 before data can be sent. 1241 Note: TMP is not intended as a generalized multiplexing protocol. If 1242 you are designing a different protocol that needs multiplexing, TMP 1243 may or may not be appropriate. Protocols with large messages can 1244 exceed the buffering capabilities of the receiver, and under certain 1245 conditions this can cause deadlock. TMP when used with TIP does not 1246 suffer from this problem since TIP is a request-response protocol, 1247 and all messages are short. 1249 A.2. Protocol Model 1251 The basic protocol model is that of multiple lightweight connections 1252 operating over a reliable stream of bytes. The party which initiated 1253 the connection is referred to as the primary, and the party which 1254 accepted the connection is referred to as the secondary. 1256 Connections may be unidirectional or bi-directional; each end of a 1257 bi-directional connection may be closed separately. Connections may 1258 be closed normally, or reset to indicate an abortive release. 1259 Aborting a connection closes both data streams. 1261 Once a connection has been opened, applications can send messages 1262 over it, and signal the end of application level messages. 1263 Application messages are encapsulated in TMP packets and transferred 1264 over the byte stream. A single TIP command (TMP application message) 1265 must be wholly contained within a single TMP packet. 1267 A.3. TMP Packet Format 1269 A TMP packet consists of a 64 bit header followed by zero or more 1270 octets of data. The header contains three fields; a flag byte, the 1271 connection identifier, and the packet length. Both integers, the 1272 connection identifier and the packet length must be sent in network 1273 byte order. 1275 FLAGS 1276 +--------+--------+--------+--------+ 1277 |SFPR0000| Connection ID | 1278 +--------+--------+--------+--------+ 1279 | | Length | 1280 +--------+--------+--------+--------+ 1281 A.3.1. Flag Details 1283 +-------+-----------+-----------------------------------------+ 1284 | Name | Mask | Description | 1285 +-------+-----------+ ----------------------------------------+ 1286 | SYN | 1xxx|0000 | Open a new connection | 1287 | FIN | x1xx|0000 | Close an existing connection | 1288 | PUSH | xx1x|0000 | Mark application level message boundary | 1289 | RESET | xxx1|0000 | Abort the connection | 1290 +-------+-----------+-----------------------------------------+ 1292 A.4. Connection Identifiers 1294 Each TMP connection is identified by a 24 bit integer. TMP 1295 connections created by the party which initiated the underlying TCP 1296 connection must have even identifiers; those created by the other 1297 party must have odd identifiers. 1299 A.5. TMP Connection States 1301 TMP connections can exist in several different states; Closed, 1302 OpenWrite, OpenSynRead, OpenSynReset, OpenReadWrite, CloseWrite, and 1303 CloseRead. A connection can change its state in response to 1304 receiving a packet with the SYN, FIN, or RESET bits set, or in 1305 response to an API call by the application. The available API calls 1306 are open, close, and abort. 1308 The meaning of most states is obvious (e.g. OpenWrite means that a 1309 connection has been opened for writing). The meaning of the states 1310 OpenSynRead and OpenResetRead need more explanation. 1312 In the OpenSynRead state a primary opened and immediately closed the 1313 output data stream of a connection, and is now waiting for a SYN 1314 response from the secondary to open the input data stream for 1315 reading. 1317 In the OpenResetRead state a primary opened and immediately aborted 1318 a connection, and is now waiting for a SYN response from the 1319 secondary to finally close the connection. 1321 A.6. Event Priorities and State Transitions 1323 The state table shown below describes the actions and state 1324 transitions that occur in response to a given event. The events 1325 accepted by each state are listed in priority order with highest 1326 priority first. If multiple events are present in a message, those 1327 events matching the list are processed. If multiple events match, 1328 the event with the highest priority is accepted and processed first. 1329 Any remaining events are processed in the resultant successor state. 1331 For example, if a TMP connection at the secondary is in the Closed 1332 state, and the secondary receives a packet containing a SYN event, a 1333 FIN event and an input data event (i.e. DATA-IN), the secondary 1334 first accepts the SYN event (because it is the only match in Closed 1335 state). The secondary accepts the connection, sends a SYN event and 1336 enters the ReadWrite state. The SYN event is removed from the list 1337 of pending events. The remaining events are FIN and DATA-IN. In the 1338 ReadWrite state the secondary reads the input data (i.e. the DATA-IN 1339 event is processed first because it has higher priority than the FIN 1340 event). Once the data has been read and the DATA-IN event has been 1341 removed from the list of pending events, the FIN event is processed 1342 and the secondary enters the CloseWrite state. 1344 If the secondary receives a packet containing a SYN event, and is 1345 for some reason unable to accept the connection (e.g. insufficient 1346 resources), it should reject the request by sending a SYN event 1347 followed by a RESET event. Note that both events can be sent as part 1348 of the same TMP packet. 1350 If either party receives a TMP packet that it does not understand, 1351 or an event in an incorrect state, it closes the TCP connection. 1353 +==============+=========+==========+==============+ 1354 | Entry State | Event | Action | Exit State | 1355 +==============+=========+==========+==============+ 1356 | Closed | SYN | SYN | ReadWrite | 1357 | | OPEN | SYN | OpenWrite | 1358 +--------------+---------+----------+--------------+ 1359 | OpenWrite | SYN | Accept | ReadWrite | 1360 | | WRITE | DATA-OUT | OpenWrite | 1361 | | CLOSE | FIN | OpenSynRead | 1362 | | ABORT | RESET | OpenSynReset | 1363 +--------------+---------+----------+--------------+ 1364 | OpenSynRead | SYN | Accept | CloseRead | 1365 +--------------+---------+----------+--------------+ 1366 | OpenSynReset | SYN | Accept | Closed | 1367 +--------------+---------+----------+--------------+ 1368 | ReadWrite | DATA-IN | Accept | ReadWrite | 1369 | | FIN | Accept | CloseWrite | 1370 | | RESET | Accept | Closed | 1371 | | WRITE | DATA-OUT | ReadWrite | 1372 | | CLOSE | FIN | CloseRead | 1373 | | ABORT | RESET | Closed | 1374 +--------------+---------+----------+--------------+ 1375 | CloseWrite | RESET | Accept | Closed | 1376 | | WRITE | DATA-OUT | CloseWrite | 1377 | | CLOSE | FIN | Closed | 1378 | | ABORT | RESET | Closed | 1379 +--------------+---------+----------+--------------+ 1380 | CloseRead | DATA-IN | Accept | CloseRead | 1381 | | FIN | Accept | Closed | 1382 | | RESET | Accept | Closed | 1383 | | ABORT | RESET | Closed | 1384 +--------------+---------+----------+--------------+ 1386 TMP Event Priorities and State Transitions