idnits 2.17.1 draft-ietf-beep-framework-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1548: '...s identification MUST start with "x-"....' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1671 has weird spacing: '...reeting err...' == Line 1762 has weird spacing: '... code mea...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 25, 2000) is 8586 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) -- Looks like a reference, but probably isn't: 'RFC-2396' on line 1645 -- Looks like a reference, but probably isn't: 'RFC-1766' on line 1654 -- Looks like a reference, but probably isn't: '1-5' on line 1657 -- Looks like a reference, but probably isn't: '1-9' on line 1657 == Unused Reference: '11' is defined on line 1890, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-mrose-beep-design-00 ** Downref: Normative reference to an Informational draft: draft-mrose-beep-design (ref. '1') -- Possible downref: Non-RFC (?) normative reference: ref. '3' ** Obsolete normative reference: RFC 2246 (ref. '4') (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2222 (ref. '5') (Obsoleted by RFC 4422, RFC 4752) == Outdated reference: A later version (-06) exists of draft-ietf-beep-tcpmapping-02 ** Obsolete normative reference: RFC 793 (ref. '7') (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 2234 (ref. '8') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 1766 (ref. '9') (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2396 (ref. '10') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2401 (ref. '12') (Obsoleted by RFC 4301) ** Obsolete normative reference: RFC 2078 (ref. '13') (Obsoleted by RFC 2743) -- Possible downref: Non-RFC (?) normative reference: ref. '14' -- Possible downref: Non-RFC (?) normative reference: ref. '15' Summary: 12 errors (**), 0 flaws (~~), 8 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M.T. Rose 3 Internet-Draft Invisible Worlds, Inc. 4 Expires: March 26, 2001 September 25, 2000 6 The Blocks Extensible Exchange Protocol Framework 7 draft-ietf-beep-framework-02 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that 16 other groups may also distribute working documents as 17 Internet-Drafts. 19 Internet-Drafts are draft documents valid for a maximum of six 20 months and may be updated, replaced, or obsoleted by other documents 21 at any time. It is inappropriate to use Internet-Drafts as reference 22 material or to cite them other than as "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt. 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 This Internet-Draft will expire on March 26, 2001. 32 Copyright Notice 34 Copyright (C) The Internet Society (2000). All Rights Reserved. 36 Abstract 38 This memo describes a generic application protocol framework for 39 connection-oriented, asynchronous interactions. The framework 40 permits simultaneous and independent exchanges within the context of 41 a single application user-identity, supporting both textual and 42 binary messages. 44 Table of Contents 46 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 47 2. The BEEP Framework . . . . . . . . . . . . . . . . . . . . 5 48 2.1 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 49 2.1.1 Exchange Styles . . . . . . . . . . . . . . . . . . . . . 6 50 2.2 Messages and Frames . . . . . . . . . . . . . . . . . . . 7 51 2.2.1 Frame Syntax . . . . . . . . . . . . . . . . . . . . . . . 8 52 2.2.1.1 Frame Header . . . . . . . . . . . . . . . . . . . . . . . 9 53 2.2.1.2 Frame Payload . . . . . . . . . . . . . . . . . . . . . . 12 54 2.2.1.3 Frame Trailer . . . . . . . . . . . . . . . . . . . . . . 13 55 2.2.2 Frame Semantics . . . . . . . . . . . . . . . . . . . . . 14 56 2.2.2.1 Poorly-formed Messages . . . . . . . . . . . . . . . . . . 14 57 2.2.2.2 XML-based Profiles . . . . . . . . . . . . . . . . . . . . 15 58 2.3 Channel Management . . . . . . . . . . . . . . . . . . . . 16 59 2.3.1 Message Semantics . . . . . . . . . . . . . . . . . . . . 17 60 2.3.1.1 The Greeting Message . . . . . . . . . . . . . . . . . . . 17 61 2.3.1.2 The Start Message . . . . . . . . . . . . . . . . . . . . 19 62 2.3.1.3 The Close Message . . . . . . . . . . . . . . . . . . . . 22 63 2.3.1.4 The OK Message . . . . . . . . . . . . . . . . . . . . . . 24 64 2.3.1.5 The Error Message . . . . . . . . . . . . . . . . . . . . 24 65 2.4 Session Establishment and Release . . . . . . . . . . . . 26 66 2.5 Transport Mappings . . . . . . . . . . . . . . . . . . . . 28 67 2.5.1 Session Management . . . . . . . . . . . . . . . . . . . . 28 68 2.5.2 Message Exchange . . . . . . . . . . . . . . . . . . . . . 28 69 2.6 Parallelism . . . . . . . . . . . . . . . . . . . . . . . 29 70 2.6.1 Within a Single Channel . . . . . . . . . . . . . . . . . 29 71 2.6.2 Between Different Channels . . . . . . . . . . . . . . . . 29 72 2.6.3 Pre-emptive Replies . . . . . . . . . . . . . . . . . . . 29 73 2.6.4 Interference . . . . . . . . . . . . . . . . . . . . . . . 29 74 2.7 Peer-to-Peer Behavior . . . . . . . . . . . . . . . . . . 30 75 3. Transport Security . . . . . . . . . . . . . . . . . . . . 31 76 3.1 The TLS Transport Security Profile . . . . . . . . . . . . 34 77 3.1.1 Profile Identification and Initialization . . . . . . . . 34 78 3.1.2 Message Syntax . . . . . . . . . . . . . . . . . . . . . . 35 79 3.1.3 Message Semantics . . . . . . . . . . . . . . . . . . . . 36 80 3.1.3.1 The Ready Message . . . . . . . . . . . . . . . . . . . . 36 81 3.1.3.2 The Proceed Message . . . . . . . . . . . . . . . . . . . 36 82 4. User Authentication . . . . . . . . . . . . . . . . . . . 37 83 4.1 The SASL Family of Profiles . . . . . . . . . . . . . . . 38 84 4.1.1 Profile Identification and Initialization . . . . . . . . 39 85 4.1.2 Message Syntax . . . . . . . . . . . . . . . . . . . . . . 42 86 4.1.3 Message Semantics . . . . . . . . . . . . . . . . . . . . 43 87 5. Registration Templates . . . . . . . . . . . . . . . . . . 44 88 5.1 Profile Registration Template . . . . . . . . . . . . . . 44 89 5.2 Feature Registration Template . . . . . . . . . . . . . . 44 90 6. Initial Registrations . . . . . . . . . . . . . . . . . . 45 91 6.1 Registration: BEEP Channel Management . . . . . . . . . . 45 92 6.2 Registration: TLS Transport Security Profile . . . . . . . 45 93 6.3 Registration: SASL Family of Profiles . . . . . . . . . . 46 94 7. DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 95 7.1 BEEP Channel Management DTD . . . . . . . . . . . . . . . 47 96 7.2 TLS Transport Security Profile DTD . . . . . . . . . . . . 49 97 7.3 SASL Family of Profiles DTD . . . . . . . . . . . . . . . 50 98 8. Reply Codes . . . . . . . . . . . . . . . . . . . . . . . 51 99 9. Security Considerations . . . . . . . . . . . . . . . . . 52 100 10. IANA Considerations . . . . . . . . . . . . . . . . . . . 53 101 References . . . . . . . . . . . . . . . . . . . . . . . . 54 102 Author's Address . . . . . . . . . . . . . . . . . . . . . 55 103 A. Changes from draft-ietf-beep-framework-01 . . . . . . . . 56 104 B. Changes from draft-ietf-beep-framework-00 . . . . . . . . 57 105 C. Changes from draft-mrose-bxxp-framework-01 . . . . . . . . 58 106 D. Changes from draft-mrose-bxxp-framework-00 . . . . . . . . 59 107 E. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 60 108 Full Copyright Statement . . . . . . . . . . . . . . . . . 61 110 1. Introduction 112 This memo describes a generic application protocol framework for 113 connection-oriented, asynchronous interactions. Consult [1] for a 114 description of the framework's design principles. 116 At the core of the BEEP framework is a framing mechanism that 117 permits simultaneous and independent exchanges of messages between 118 peers. Messages are arbitrary MIME[2] content, but are usually 119 textual (structured using XML[3]). 121 All exchanges occur in the context of a channel -- a binding to a 122 well-defined aspect of the application, such as transport security, 123 user authentication, or data exchange. 125 Each channel has an associated "profile" that defines the syntax and 126 semantics of the messages exchanged. Implicit in the operation of 127 BEEP is the notion of channel management. In addition to defining 128 BEEP's channel management profile, this document defines: 130 o the TLS[4] transport security profile; and, 132 o the SASL[5] family of profiles. 134 Other profiles, such as those used for data exchange, are defined by 135 an application protocol designer. 137 2. The BEEP Framework 139 A BEEP session is mapped onto an underlying transport service. A 140 separate series of documents describe how a particular transport 141 service realizes a BEEP session. For example, [6] describes how a 142 BEEP session is mapped onto a single TCP[7] connection. 144 When a session is established, each BEEP peer advertises the profile 145 it supports. Later on, during the creation of a channel, the client 146 supplies one or more proposed profiles for that channel. If the 147 server creates the channel, it selects one of the profiles and sends 148 it in a reply; otherwise, it may indicate that none of the profiles 149 are acceptable, and decline creation of the channel. 151 Channel usage falls into one of two categories: 153 initial tuning: these are used by profiles that perform 154 initialization once the BEEP session is established (e.g., 155 negotiating the use of transport security); although several 156 exchanges may be required to perform the initialization, these 157 channels become inactive early in the BEEP session and remain so 158 for the duration. 160 continuous: these are used by profiles that support data exchange; 161 typically, these channels are created after the initial tuning 162 channels have gone quiet. 164 2.1 Roles 166 Although BEEP is peer-to-peer, it is convenient to label each peer 167 in the context of the role it is performing at a given time: 169 o When a BEEP session is established, the peer that awaits new 170 connections is acting in the listening role, and the other peer, 171 which establishes a connection to the listener, is acting in the 172 initiating role. In the examples which follow, these are referred 173 to as "L:" and "I:", respectively. 175 o A BEEP peer starting an exchange is termed the client; similarly, 176 the other BEEP peer is termed the server. In the examples which 177 follow, these are referred to as "C:" and "S:", respectively. 179 Typically, a BEEP peer acting in the server role is also acting in a 180 listening role. However, because BEEP is peer-to-peer in nature, no 181 such requirement exists. 183 2.1.1 Exchange Styles 185 BEEP allows three styles of exchange: 187 MSG/RPY: the client sends a "MSG" message asking the server to 188 perform some task, the server performs the task and replies with 189 a "RPY" message (termed a positive reply). 191 MSG/ERR: the client sends a "MSG" message, the server does not 192 perform any task and replies with an "ERR" message (termed a 193 negative reply). 195 MSG/ANS: the client sends a "MSG" message, the server, during the 196 course of performing some task, replies with zero or more "ANS" 197 messages, and, upon completion of the task, sends a "NUL" 198 message, which signifies the end of the reply. 200 The first two styles are termed one-to-one exchanges, whilst the 201 third style is termed a one-to-many exchange. 203 2.2 Messages and Frames 205 A message is structured according to the rules of MIME. Accordingly, 206 each message may begin with "entity-headers" (c.f., MIME[2]'s 207 Section 3). If none, or only some, of the "entity-headers" are 208 present: 210 o the default "Content-Type" is "application/octet-stream"; and, 212 o the default "Content-Transfer-Encoding" is "binary". 214 Normally, a message is sent in a single frame. However, it may be 215 convenient or necesary to segment a message into multiple frames 216 (e.g., if only part of a message is ready to be sent). 218 Each frame consists of a header, the payload, and a trailer. The 219 header and trailer are each represented using printable ASCII 220 characters and are terminated with a CRLF pair. Between the header 221 and the trailer is the payload, consisting of zero or more octets. 223 For example, here is a message contained in a single frame that 224 contains a payload of 119 octets spread over 5 lines (each line is 225 terminated with a CRLF pair): 227 C: MSG 0 1 . 40 120 228 C: Content-Type: text/xml 229 C: 230 C: 231 C: 232 C: 233 C: END 234 C: 236 In this example, note that the entire message is represented in a 237 single frame. 239 2.2.1 Frame Syntax 241 The ABNF[8] for a frame is: 243 frame = data / mapping 245 data = header payload trailer 247 header = msg / rpy / err / ans / nul 249 msg = "MSG" SP common CR LF 250 rpy = "RPY" SP common CR LF 251 ans = "ANS" SP common SP ansno CR LF 252 err = "ERR" SP common CR LF 253 nul = "NUL" SP common CR LF 255 common = channel SP msgno SP more SP seqno SP size 256 channel = 0..2147483647 257 msgno = 0..2147483647 258 more = "." / "*" 259 seqno = 0..4294967295 260 size = 0..2147483647 261 ansno = 0..2147483647 263 payload = *OCTET 265 trailer = "END" CR LF 267 mapping = ;; each transport mapping may define additional frames 269 2.2.1.1 Frame Header 271 The frame header consists of a three-character keyword (one of: 272 "MSG", "RPY", "ERR", "ANS", or "NUL"), followed by zero or more 273 parameters. A single space character (decimal code 32, " ") 274 separates each component. The header is terminated with a CRLF pair. 276 The channel number ("channel") must be a non-negative integer (in 277 the range 0..2147483647). 279 The message number ("msgno") must be a non-negative integer (in the 280 range 0..2147483647) and have a different value than all other "MSG" 281 messages for which a reply has not been completely received. 283 The continuation indicator ("more", one of: decimal code 42, "*", or 284 decimal code 46, ".") specifies whether this is the final frame of 285 the message: 287 intermediate ("*"): at least one other frame follows for the 288 message; or, 290 complete ("."): this frame completes the message. 292 The sequence number ("seqno") must be a non-negative integer (in the 293 range 0..4294967295) and specifies the sequence number of the first 294 octet in the payload, for the associated channel. 296 The payload size ("size") must be a non-negative integer (in the 297 range 0..2147483647) and specifies the exact number of octets in the 298 payload. (This does not include either the header or trailer.) 300 Note that a frame may have an empty payload, e.g., 302 S: RPY 0 1 * 287 20 303 S: ... 304 S: ... 305 S: END 306 S: 307 S: RPY 0 1 . 307 0 308 S: END 309 S: 311 The answer number ("ansno") must be a non-negative integer (in the 312 range 0..4294967295) and must have a different value than all other 313 answers in progress for the message being replied to. 315 There are two kinds of frames: data and mapping. each transport 316 mapping (c.f., Section 2.5) may define its own frames. For example, 317 [6] defines the SEQ frame. The remainder of this section discusses 318 data frames. 320 When a message is segmented and sent as several frames, those frames 321 must be sent sequentally, without any intervening frames from other 322 messages on the same channel. However, there are two exceptions: 323 first, no restriction is made with respect to the interleaving of 324 frames for other channels; and, second, in a one-to-many exchange, 325 multiple answers may be simultaneously in progress. Accordingly, 326 frames for "ANS" messages may be interleaved on the same channel -- 327 the answer number is used for collation, e.g., 329 S: ANS 1 0 * 0 20 0 330 S: ... 331 S: ... 332 S: END 333 S: 334 S: ANS 1 0 * 20 20 1 335 S: ... 336 S: ... 337 S: END 338 S: 339 S: ANS 1 0 . 40 10 0 340 S: ... 341 S: END 342 S: 344 which shows two "ANS" messages interleaved on channel 1 as part of a 345 reply to message number 0. Note that the sequence number is advanced 346 for each frame sent on the channel, and is independent of the 347 messages sent in those frames. 349 There are several rules for identifying poorly-formed frames: 351 o if the header doesn't start with "MSG", "RPY", "ERR", "ANS", or 352 "NUL"; 354 o if any of the parameters in the header cannot be determined or 355 are invalid (i.e., syntactically incorrect); 357 o if the value of the channel number doesn't refer to an existing 358 channel; 360 o if the header starts with "MSG", and the message number refers to 361 a "MSG" message that has been completely received but for which a 362 reply has not been completely sent; 364 o if the header doesn't start with "MSG", and refers to a message 365 number for which a reply has not been completely received; 367 o if the header doesn't start with "MSG", and refers to a message 368 number that has never been sent (except during session 369 establishment, c.f., Section 2.3.1.1); 371 o if the header starts with "MSG", "ERR", or "ANS", and refers to a 372 message number for which at least one other frame has been 373 received, and the three-character keyword starting this frame and 374 the immediately-previous received frame for this reply are not 375 identical; 377 o if the header starts with "NUL", and refers to a message number 378 for which at least one other frame has been received, and the 379 keyword of of the immediately-previous received frame for this 380 reply isn't "ANS"; 382 o if the continuation indicator of the previous frame received on 383 the same channel was intermediate ("*"), and its message number 384 isn't identical to this frame's message number; 386 o if the value of the sequence number doesn't correspond to the 387 expected value for the associated channel (c.f., Section 388 2.2.1.2); or, 390 o if the header starts with "NUL", and the continuation indicator 391 is intermediate ("*") or the payload size is non-zero. 393 If a frame is poorly-formed, then the session is terminated without 394 generating a response, and it is recommended that a diagnostic entry 395 be logged. 397 2.2.1.2 Frame Payload 399 The frame payload consists of zero or more octets. 401 Every payload octet sent in each direction on a channel has an 402 associated sequence number. Numbering of payload octets within a 403 frame is such that the first payload octet is the lowest numbered, 404 and the following payload octets are numbered consecutively. (When a 405 channel is created, the sequence number associated with the first 406 payload octet of the first frame is 0.) 408 The actual sequence number space is finite, though very large, 409 ranging from 0..4294967295 (2**32 - 1). Since the space is finite, 410 all arithmetic dealing with sequence numbers is performed modulo 411 2**32. This unsigned arithmetic preserves the relationship of 412 sequence numbers as they cycle from 2**32 - 1 to 0 again. 414 When receiving a frame, the sum of its sequence number and payload 415 size, modulo 4294967296 (2**32), gives the expected sequence number 416 associated with the first payload octet of the next frame received. 417 Accordingly, when receiving a frame if the sequence number isn't the 418 expected value for this channel, then the BEEP peers have lost 419 synchronization, then the session is terminated without generating a 420 response, and it is recommended that a diagnostic entry be logged. 422 2.2.1.3 Frame Trailer 424 The frame trailer consists of "END" followed by a CRLF pair. 426 When receiving a frame, if the characters immediately following the 427 payload don't correspond to a trailer, then the session is 428 terminated without generating a response, and it is recommended that 429 a diagnostic entry be logged. 431 2.2.2 Frame Semantics 433 The semantics of each message is channel-specific. Accordingly, the 434 profile associated with a channel must define: 436 o the initialization messages, if any, exchanged during channel 437 creation; 439 o the messages that may be exchanged in the payload of the channel; 440 and, 442 o the semantics of these messages. 444 A profile registration template (Section 5.1) organizes this 445 information. 447 2.2.2.1 Poorly-formed Messages 449 When defining the behavior of the profile, the template must specify 450 how poorly-formed "MSG" messages are replied to. For example, the 451 channel management profile sends a negative reply containing an 452 error message (c.f., Section 2.3.1.5). 454 If a poorly-formed reply is received on channel zero, the session is 455 terminated without generating a response, and it is recommended that 456 a diagnostic entry be logged. 458 If a poorly-formed reply is received on another channel, then the 459 channel must be closed using the procedure in Section 2.3.1.3. 461 2.2.2.2 XML-based Profiles 463 If a profile uses XML[3] to structure its messages, then only XML's 464 baseline facilities (as described in the XML 1.0 specification[3]) 465 are allowed. Additional XML facilities (e.g., namespaces) are made 466 available only by being explicitly permitted in a given profile's 467 specification. 469 In particular this limitation allows use of only the five predefined 470 general entities references ("&", "<", ">", "'", and 471 """) and numeric entity references in the messages exchanged. 473 Further, because the profile registration template defines the 474 messages exchanged over a channel, the XML documents exchanged in 475 each message needn't have either a "XML" declaration (e.g., ) or a "DOCTYPE" declaration (e.g., ). 477 All other XML 1.0 instructions (e.g., CDATA blocks, processing 478 instructions, and so on) are allowed. 480 Finally, because the "XML" declaration isn't present, the default 481 character set for XML-based profiles is UTF-8. If another character 482 set is desired, the "Content-Type" entity-header must indicate this. 484 2.3 Channel Management 486 When a BEEP session starts, only channel number zero is defined, 487 which is used for channel management. Section 6.1 contains the 488 profile registration for BEEP channel management. 490 Channel management allows each BEEP peer to advertise the profiles 491 that it supports (c.f., Section 2.3.1.1), bind an instance of one of 492 those profiles to a channel (c.f., Section 2.3.1.2), and then later 493 close any channels or release the BEEP session (c.f., Section 494 2.3.1.3). 496 A BEEP peer should support at least 257 concurrent channels. 498 2.3.1 Message Semantics 500 2.3.1.1 The Greeting Message 502 When a BEEP session is established, each BEEP peer signifies its 503 availability by immediately sending a positive reply with a message 504 number of zero that contains a "greeting" element, e.g., 506 L: 507 I: 508 L: RPY 0 0 . 0 110 509 L: Content-Type: text/xml 510 L: 511 L: 512 L: 513 L: 514 L: END 515 L: 516 I: RPY 0 0 . 0 40 517 I: Content-Type: text/xml 518 I: 519 I: 520 I: END 521 I: 523 Note that this example implies that the BEEP peer in the initiating 524 role waits until the BEEP peer in the listening role sends its 525 greeting -- this is an artifact of the presentation; in fact, both 526 BEEP peers send their replies independently. 528 The "greeting" element has two optional attributes ("features" and 529 "localize") and zero or more "profile" elements, one for each 530 profile supported by the BEEP peer acting in a server role: 532 o the "features" attribute, if present, contains one or more 533 feature tokens, each indicating an optional feature of the 534 channel management profile supported by the BEEP peer; 536 o the "localize" attribute, if present, contains one or more 537 language tokens (defined in [9]), each identifying a desirable 538 language tag to be used by the remote BEEP peer when generating 539 textual diagnostics for the "close" and "error" elements (the 540 tokens are ordered from most to least desirable); and, 542 o each "profile" element contained within the "greeting" element 543 identifies a profile, and unlike the "profile" elements that 544 occur within the "start" element, the content of each "profile" 545 element may not contain an optional initialization message. 547 At present, there are no optional features defined for the channel 548 management profile. 550 Section 5.2 defines a registration template for optional features. 552 2.3.1.2 The Start Message 554 When a BEEP peer wants to create a channel, it sends a "start" 555 element on channel zero, e.g., 557 C: MSG 0 1 . 40 120 558 C: Content-Type: text/xml 559 C: 560 C: 561 C: 562 C: 563 C: END 564 C: 566 The "start" element has a "number" attribute, an optional 567 "serverName" attribute, and one or more "profile" elements: 569 o the "number" attribute indicates the channel number (in the range 570 1..2147483647) used to identify the channel in future messages; 572 o the "serverName" attribute, an arbitrary string, indicates the 573 desired server name for this BEEP session; and, 575 o each "profile" element contained with the "start" element has a 576 "uri" attribute, an optional "encoding" attribute, and arbitrary 577 character data as content: 579 * the "uri" attribute authoritatively identifies the profile; 581 * the "encoding" attribute, if present, specifies whether the 582 content of the "profile" element is represented as a 583 base64-encoded string; and, 585 * the content of the "profile" element, if present, must be no 586 longer than 4K octets in length and specifies an 587 initialization message given to the channel as soon as it is 588 created. 590 To avoid conflict in assigning channel numbers when requesting the 591 creation of a channel, BEEP peers acting in the initiating role use 592 only positive integers that are odd-numbered; similarly, BEEP peers 593 acting in the listening role use only positive integers that are 594 even-numbered. 596 The "serverName" attribute for the first successful "start" element 597 received by a BEEP peer is meaningful for the duration of the BEEP 598 session. If present, the BEEP peer decides whether to operate as the 599 indicated "serverName"; if not, an "error" element is sent in a 600 negative reply. 602 When a BEEP peer receives a "start" element on channel zero, it 603 examines each of the proposed profiles, and decides whether to use 604 one of them to create the channel. If so, the appropriate "profile" 605 element is sent in a positive reply; otherwise, an "error" element 606 is sent in a negative reply. 608 When creating the channel, the value of the "serverName" attribute 609 from the first successful "start" element is consulted to provide 610 configuration information, e.g., the desired server-side certificate 611 when starting the TLS transport security profile (Section 3.1). 613 For example, a successful channel creation might look like this: 615 C: MSG 0 1 . 40 197 616 C: Content-Type: text/xml 617 C: 618 C: 619 C: 620 C: 622 C: 623 C: END 624 C: 625 S: RPY 0 1 . 252 87 626 S: Content-Type: text/xml 627 S: 628 S: 629 S: END 630 S: 632 Similarly, an unsuccessful channel creation might look like this: 634 C: MSG 0 1 . 40 120 635 C: Content-Type: text/xml 636 C: 637 C: 638 C: 639 C: 640 C: END 641 C: 642 S: ERR 0 1 . 252 115 643 S: Content-Type: text/xml 644 S: 645 S: number attribute 646 S: in <start> element must be odd-valued 647 S: END 648 S: 650 Finally, here's an example in which an initialization element is 651 exchanged during channel creation: 653 C: MSG 0 1 . 40 158 654 C: Content-Type: text/xml 655 C: 656 C: 657 C: 658 C: ]]> 659 C: 660 C: 661 C: END 662 C: 663 S: RPY 0 1 . 110 121 664 S: Content-Type: text/xml 665 S: 666 S: 667 S: ]]> 668 S: 669 S: END 670 S: 672 2.3.1.3 The Close Message 674 When a BEEP peer wants to close a channel, it sends a "close" 675 element on channel zero, e.g., 677 C: MSG 0 2 . 223 59 678 C: Content-Type: text/xml 679 C: 680 C: 681 C: END 682 C: 684 The "close" element has a "number" attribute, a "code" attribute, an 685 optional "xml:lang" attribute, and an optional textual diagnostic as 686 its content: 688 o the "number" attribute indicates the channel number; 690 o the "code" attribute is a three-digit reply code meaningful to 691 programs (c.f., Section 8); 693 o the "xml:lang" attribute identifies the language that the 694 element's content is written in (the value is suggested, but not 695 mandated, by the "localize" attribute of the "greeting" element 696 sent by the remote BEEP peer); and, 698 o the textual diagnostic (which may be multiline) is meaningful to 699 implementers, perhaps administrators, and possibly even users, 700 but never programs. 702 Note that if the textual diagnostic is present, then the "xml:lang" 703 attribute is absent only if the language indicated as the remote 704 BEEP peer's first choice is used. 706 If the value of the "number" attribute is zero, then the BEEP peer 707 wants to release the BEEP session (c.f., Section 2.4) -- otherwise 708 the value of the "number" attribute refers to an existing channel. 710 When a BEEP peer receives a "close" element on channel zero, it 711 decides whether it is willing to close the channel. If so, an "ok" 712 element is sent in a positive reply; otherwise, an "error" element 713 is sent in a negative reply. 715 For example, a successful channel close might look like this: 717 C: MSG 0 2 . 223 59 718 C: Content-Type: text/xml 719 C: 720 C: 721 C: END 722 C: 723 S: RPY 0 2 . 423 34 724 S: Content-Type: text/xml 725 S: 726 S: 727 S: END 728 S: 730 Similarly, an unsuccessful channel close might look like this: 732 C: MSG 0 2 . 223 59 733 C: Content-Type: text/xml 734 C: 735 C: 736 C: END 737 C: 738 S: ERR 0 2 . 423 67 739 S: Content-Type: text/xml 740 S: 741 S: still working 742 S: END 743 S: 745 2.3.1.4 The OK Message 747 When a BEEP peer agrees to close a channel (or release the BEEP 748 session), it sends an "ok" element in a positive reply. 750 The "ok" element has no attributes and no content. 752 2.3.1.5 The Error Message 754 When a BEEP peer declines the creation of a channel, it sends an 755 "error" element in a negative reply, e.g., 757 I: MSG 0 1 . 40 115 758 I: Content-Type: text/xml 759 I: 760 I: 761 I: 762 I: 763 I: END 764 I: 765 L: ERR 0 1 . 252 93 766 L: Content-Type: text/xml 767 L: 768 L: all requested profiles are 769 L: unsupported 770 L: END 771 L: 773 The "error" element has a "code" attribute, an optional "xml:lang" 774 attribute, and an optional textual diagnostic as its content: 776 o the "code" attribute is a three-digit reply code meaningful to 777 programs (c.f., Section 8); 779 o the "xml:lang" attribute identifies the language that the 780 element's content is written in (the value is suggested, but not 781 mandated, by the "localize" attribute of the "greeting" element 782 sent by the remote BEEP peer); and, 784 o the textual diagnostic (which may be multiline) is meaningful to 785 implementers, perhaps administrators, and possibly even users, 786 but never programs. 788 Note that if the textual diagnostic is present, then the "xml:lang" 789 attribute is absent only if the language indicated as the remote 790 BEEP peer's first choice is used. 792 In addition, a BEEP peer sends an "error" element whenever: 794 o it receives a "MSG" message containing a poorly-formed or 795 unexpected element; 797 o it receives a "MSG" message asking to close a channel (or release 798 the BEEP session) and it declines to do so; or 800 o a BEEP session is established, the BEEP peer is acting in the 801 listening role, and that BEEP peer is unavailable (in this case, 802 the BEEP acting in the listening role does not send a "greeting" 803 element). 805 In the final case, both BEEP peers terminate the session, and it is 806 recommended that a diagnostic entry be logged by both BEEP peers. 808 2.4 Session Establishment and Release 810 When a BEEP session is established, each BEEP peer signifies its 811 availability by immediately sending a positive reply with a message 812 number of zero on channel zero that contains a "greeting" element, 813 e.g., 815 L: 816 I: 817 L: RPY 0 0 . 0 110 818 L: Content-Type: text/xml 819 L: 820 L: 821 L: 822 L: 823 L: END 824 L: 825 I: RPY 0 0 . 0 40 826 I: Content-Type: text/xml 827 I: 828 I: 829 I: END 830 I: 832 Alternatively, if the BEEP peer acting in the listening role is 833 unavailable, it sends a negative reply, e.g., 835 L: 836 I: 837 L: ERR 0 0 . 0 48 838 L: Content-Type: text/xml 839 L: 840 L: 841 L: END 842 L: 843 I: RPY 0 0 . 0 40 844 I: Content-Type: text/xml 845 I: 846 I: 847 I: END 848 I: 849 I: 850 L: 851 L: 853 and the "greeting" element sent by the BEEP peer acting in the 854 initiating role is ignored. It is recommended that a diagnostic 855 entry be logged by both BEEP peers. 857 Note that both of these examples imply that the BEEP peer in the 858 initiating role waits until the BEEP peer in the listening role 859 sends its greeting -- this is an artifact of the presentation; in 860 fact, both BEEP peers send their replies independently. 862 When a BEEP peer wants to release the BEEP session, it sends a 863 "close" element with a zero-valued "number" attribute on channel 864 zero. The other BEEP peer indicates its willingness by sending an 865 "ok" element in a positive reply, e.g., 867 C: MSG 0 1 . 40 48 868 C: Content-Type: text/xml 869 C: 870 C: 871 C: END 872 C: 873 S: RPY 0 1 . 252 34 874 S: Content-Type: text/xml 875 S: 876 S: 877 S: END 878 S: 879 I: 880 L: 881 L: 883 Alternatively, if the other BEEP doesn't want to release the BEEP 884 session, the exchange might look like this: 886 C: MSG 0 1 . 40 48 887 C: Content-Type: text/xml 888 C: 889 C: 890 C: END 891 C: 892 S: ERR 0 1 . 252 67 893 S: Content-Type: text/xml 894 S: 895 S: still working 896 S: END 897 S: 899 If session release is declined, the BEEP session should not be 900 terminated, if possible. 902 2.5 Transport Mappings 904 All transport interactions occur in the context of a session -- a 905 mapping onto a particular transport service. Accordingly, this memo 906 defines the requirements that must be satisified by any document 907 describing how a particular transport service realizes a BEEP 908 session. 910 2.5.1 Session Management 912 A BEEP session is connection-oriented. A mapping document must 913 define: 915 o how a BEEP session is established; 917 o how a BEEP peer is identified as acting in the listening role; 919 o how a BEEP peer is identified as acting in the initiating role; 921 o how a BEEP session is released; and, 923 o how a BEEP session is terminated. 925 2.5.2 Message Exchange 927 A BEEP session is message-oriented. A mapping document must define: 929 o how messages are reliably sent and received; 931 o how messages on the same channel are received in the same order 932 as they were sent; and, 934 o how messages on different channels are sent without ordering 935 constraint. 937 2.6 Parallelism 939 2.6.1 Within a Single Channel 941 A BEEP peer acting in the client role may send multiple "MSG" 942 messages on the same channel without waiting to receive the 943 corresponding replies. 945 A BEEP peer acting in the server role must process all "MSG" 946 messages for a given channel in the same order as they are received. 947 As a consequence, the BEEP peer must generate replies in the same 948 order as the corresponding "MSG" messages are received on a given 949 channel. 951 2.6.2 Between Different Channels 953 A BEEP peer acting in the client role may send multiple "MSG" 954 messages on different channels without waiting to receive the 955 corresponding replies. 957 A BEEP peer acting in the server role may process "MSG" messages 958 received on different channels in any order it chooses. As a 959 consequence, although the replies for a given channel appear to be 960 generated in the same order in which the corresponding "MSG" 961 messages are received, there is no ordering constraint for replies 962 on different channels. 964 2.6.3 Pre-emptive Replies 966 A BEEP peer acting in the server role may send a negative reply 967 before it receives the final "MSG" frame of a message. If it does 968 so, that BEEP peer is obliged to ignore any subsequent "MSG" frames 969 for that message, up to and including the final "MSG" frame. 971 If a BEEP peer acting in the client role receives a negative reply 972 before it sends the final "MSG" frame for a message, then it is 973 required to send a "MSG" frame with a continuation status of 974 complete (".") and having a zero-length payload. 976 2.6.4 Interference 978 If the processing of a particular message has sequencing impacts on 979 other messages (either intra-channel or inter-channel), then the 980 corresponding profile should define this behavior, e.g., a profile 981 whose messages alter the underlying transport mapping. 983 2.7 Peer-to-Peer Behavior 985 BEEP is peer-to-peer -- as such both peers must be prepared to 986 receive all messages defined in this memo. Accordingly, an 987 initiating BEEP peer capable of acting only in the client role must 988 behave gracefully if it receives a "MSG" message. Accordingly, all 989 profiles must provide an appropriate error message for replying to 990 unexpected "MSG" messages. 992 As a consequence of the peer-to-peer nature of BEEP, message numbers 993 are unidirectionally-significant. That is, the message numbers in 994 "MSG" messages sent by a BEEP peer acting in the initiating role are 995 unrelated to the message numbers in "MSG" messages sent by a BEEP 996 peer acting in the listening role. 998 For example, these two messages 1000 I: MSG 0 1 . 40 120 1001 I: Content-Type: text/xml 1002 I: 1003 I: 1004 I: 1005 I: 1006 I: END 1007 I: 1008 L: MSG 0 1 . 252 116 1009 L: Content-Type: text/xml 1010 L: 1011 L: 1012 L: 1013 L: 1014 L: END 1015 L: 1017 refer to different messages sent on channel zero. 1019 3. Transport Security 1021 When a BEEP session is established, plaintext transfer, without 1022 privacy, is provided. Accordingly, transport security in BEEP is 1023 achieved using an initial tuning profile. 1025 This document defines one profile: 1027 o the TLS transport security profile, based on TLS version one[4]. 1029 Other profiles may be defined and deployed on a bilateral basis. 1030 Note that because of their intimate relationship with the tranpsort 1031 service, a given transport security profile tends to be relevant to 1032 a single transort mapping (c.f., Section 2.5). 1034 When a channel associated with transport security begins the 1035 underlying negotiation process, all channels (including channel 1036 zero) are closed on the BEEP session. Accordingly, upon completion 1037 of the negotiation process, regardless of its outcome, a new 1038 greeting is issued by both BEEP peers. (If the negotiation process 1039 fails, then either BEEP peer may instead terminate the session, and 1040 it is recommended that a diagnostic entry be logged.) 1042 A BEEP peer may choose to issue different greetings based on whether 1043 privacy is in use, e.g., 1045 L: 1046 I: 1047 L: RPY 0 0 . 0 110 1048 L: Content-Type: text/xml 1049 L: 1050 L: 1051 L: 1052 L: 1053 L: END 1054 L: 1055 I: RPY 0 0 . 0 40 1056 I: Content-Type: text/xml 1057 I: 1058 I: 1059 I: END 1060 I: 1061 I: MSG 0 1 . 40 158 1062 I: Content-Type: text/xml 1063 I: 1064 I: 1065 I: 1066 I: ]]> 1067 I: 1068 I: 1069 I: END 1070 I: 1071 L: RPY 0 1 . 110 121 1072 L: Content-Type: text/xml 1073 L: 1074 L: 1075 L: ]]> 1076 L: 1077 L: END 1078 L: 1080 ... successful transport security negotiation ... 1082 L: RPY 0 0 . 0 252 1083 L: Content-Type: text/xml 1084 L: 1085 L: 1086 L: 1088 L: 1089 L: 1090 L: 1091 L: END 1092 L: 1093 I: RPY 0 0 . 0 40 1094 I: Content-Type: text/xml 1095 I: 1096 I: 1097 I: END 1098 I: 1100 Of course, not all BEEP peers need be as single-minded: 1102 L: 1103 I: 1104 L: RPY 0 0 . 0 311 1105 L: Content-Type: text/xml 1106 L: 1107 L: 1108 L: 1110 L: 1111 L: 1112 L: 1113 L: 1114 L: END 1115 L: 1116 I: RPY 0 0 . 0 40 1117 I: Content-Type: text/xml 1118 I: 1119 I: 1120 I: END 1121 I: 1122 I: MSG 0 1 . 40 158 1123 I: Content-Type: text/xml 1124 I: 1125 I: 1126 I: 1127 I: ]]> 1128 I: 1129 I: 1130 I: END 1131 I: 1132 L: RPY 0 1 . 311 121 1133 L: Content-Type: text/xml 1134 L: 1135 L: 1136 L: ]]> 1137 L: 1138 L: END 1139 L: 1141 ... failed transport security negotiation ... 1143 L: RPY 0 0 . 0 311 1144 L: Content-Type: text/xml 1145 L: 1146 L: 1147 L: 1149 L: 1150 L: 1151 L: 1152 L: 1153 L: END 1154 L: 1155 I: RPY 0 0 . 0 40 1156 I: Content-Type: text/xml 1157 I: 1158 I: 1159 I: END 1160 I: 1162 3.1 The TLS Transport Security Profile 1164 Section 6.2 contains the registration for this profile. 1166 3.1.1 Profile Identification and Initialization 1168 The TLS transport security profile is identified as: 1170 http://xml.resource.org/profiles/TLS 1172 in the BEEP "profile" element during channel creation. 1174 During channel creation, the corresponding "profile" element in the 1175 BEEP "start" element may contain a "ready" element. If channel 1176 creation is successful, then before sending the corresponding reply, 1177 the BEEP peer processes the "ready" element and includes the 1178 resulting response in the reply, e.g., 1180 C: MSG 0 1 . 40 158 1181 C: Content-Type: text/xml 1182 C: 1183 C: 1184 C: 1185 C: ]]> 1186 C: 1187 C: 1188 C: END 1189 C: 1190 S: RPY 0 1 . 110 121 1191 S: Content-Type: text/xml 1192 S: 1193 S: 1194 S: ]]> 1195 S: 1196 S: END 1197 S: 1199 Note that it is possible for the channel to be created, but for the 1200 encapsulated operation to fail, e.g., 1202 C: MSG 0 1 . 40 173 1203 C: Content-Type: text/xml 1204 C: 1205 C: 1206 C: 1207 C: ]]> 1208 C: 1209 C: 1210 C: END 1211 C: 1212 S: RPY 0 1 . 110 181 1213 S: Content-Type: text/xml 1214 S: 1215 S: 1216 S: version attribute 1217 S: poorly formed in <ready> element 1218 S: 1219 S: END 1220 S: 1222 In this case, a positive reply is sent (as channel creation 1223 succeeded), but the encapsulated response contains an indication as 1224 to why the operation failed. 1226 3.1.2 Message Syntax 1228 Section 7.2 defines the messages that are used in the TLS transport 1229 security profile. 1231 3.1.3 Message Semantics 1233 3.1.3.1 The Ready Message 1235 The "ready" element has an optional "version" attribute and no 1236 content: 1238 o the "version" element defines the earliest version of TLS 1239 acceptable for use. 1241 When a BEEP peer sends the "ready" element, it must not send any 1242 further traffic on any channel until a corresponding reply is 1243 received; similarly, before processing a "ready" element, the 1244 receiving BEEP peer waits until any pending replies have been 1245 generated and sent. 1247 3.1.3.2 The Proceed Message 1249 The "proceed" element has no attributes and no content. It is sent 1250 as a reply to the "ready" element. When a BEEP peer receives the 1251 "ready" element, it begins the underlying negotiation process for 1252 transport security. 1254 4. User Authentication 1256 When a BEEP session is established, anonymous access, without trace 1257 information, is provided. Accordingly, user authentication in BEEP 1258 is achieved using an initial tuning profile. 1260 This document defines a family of profiles based on SASL mechanisms: 1262 o each mechanism in the IANA SASL registry[14] has an associated 1263 profile. 1265 Other profiles may be defined and deployed on a bilateral basis. 1267 Whenever a successful authentication occurs, on any channel, the 1268 authenticated identity is updated for all existing and future 1269 channels on the BEEP session; further, no additional attempts at 1270 authentication are allowed. 1272 Note that regardless of transport security and user authentication, 1273 authorization is an internal matter for each BEEP peer. As such, 1274 each peer may choose to restrict the operations it allows based on 1275 the authentication credentials provided (i.e., unauthorized 1276 operations might be rejected with error code 530). 1278 4.1 The SASL Family of Profiles 1280 Section 6.3 contains the registration for this profile. 1282 Note that SASL may provide both user authentication and transport 1283 security. Once transport security is successfully negotiated for a 1284 BEEP session, then a SASL security layer must not be negotiated; 1285 similarly, once any SASL negotiation is successful, a transport 1286 security profile must not begin its underlying negotiation process. 1288 Section 4 of the SASL specification[5] requires the following 1289 information be supplied by a protocol definition: 1291 service name: "beep" 1293 initiation sequence: Creating a channel using a BEEP profile 1294 corresponding to a SASL mechanism starts the exchange. An 1295 optional parameter corresponding to the "initial response" sent 1296 by the client is carried within a "blob" element during channel 1297 creation. 1299 exchange sequence: "Challenges" and "responses" are carried in 1300 exchanges of the "blob" element. The "status" attribute of the 1301 "blob" element is used both by a server indicating a successful 1302 completion of the exchange, and a client aborting the exchange, 1303 The server indicates failure of the exchange by sending an 1304 "error" element. 1306 security layer negotiation: When a security layer starts 1307 negotiation, all channels (including channel zero) are closed on 1308 the BEEP session. Accordingly, upon completion of the negotiation 1309 process, regardless of its outcome, a new greeting is issued by 1310 both BEEP peers. 1312 If a security layer is successfully negotiated, it takes effect 1313 immediately following the message that concludes the server's 1314 successful completion reply. 1316 use of the authorization identity: This is made available to all 1317 channels for the duration of the BEEP session. 1319 4.1.1 Profile Identification and Initialization 1321 Each SASL mechanism registered with the IANA is identified as: 1323 http://xml.resource.org/profiles/sasl/MECHANISM 1325 where "MECHANISM" is the token assigned to that mechanism by the 1326 IANA. 1328 Note that during channel creation, a BEEP peer may provide multiple 1329 profiles to the remote peer, e.g., 1331 C: MSG 0 1 . 40 197 1332 C: Content-Type: text/xml 1333 C: 1334 C: 1335 C: 1337 C: 1338 C: 1339 C: END 1340 C: 1341 S: RPY 0 1 . 252 87 1342 S: Content-Type: text/xml 1343 S: 1344 S: 1345 S: END 1346 S: 1348 During channel creation, the corresponding "profile" element in the 1349 BEEP "start" element may contain a "blob" element. Note that it is 1350 possible for the channel to be created, but for the encapsulated 1351 operation to fail, e.g., 1353 C: MSG 0 1 . 40 183 1354 C: Content-Type: text/xml 1355 C: 1356 C: 1357 C: 1358 C: AGJsb2NrbWFzdGVy]]> 1359 C: 1360 C: 1361 C: END 1362 C: 1363 S: RPY 0 1 . 252 166 1364 S: Content-Type: text/xml 1365 S: 1366 S: 1367 S: authentication mechanism is 1368 S: too weak 1369 S: 1370 S: END 1371 S: 1373 In this case, a positive reply is sent (as channel creation 1374 succeeded), but the encapsulated response contains an indication as 1375 to why the operation failed. 1377 Otherwise, the server sends a challenge (or signifies success), e.g., 1379 C: MSG 0 1 . 40 183 1380 C: Content-Type: text/xml 1381 C: 1382 C: 1383 C: 1384 C: AGJsb2NrbWFzdGVy]]> 1385 C: 1386 C: 1387 C: END 1388 C: 1389 S: RPY 0 1 . 252 171 1390 S: Content-Type: text/xml 1391 S: 1392 S: 1393 S: b3RwLXNoYTEgOTk5NyBwaXh5bWlzYXM4NTgwNSBleHQ= 1394 ]]> 1395 S: 1396 S: END 1397 S: 1399 Note that this example implies that the "blob" element in the 1400 server's reply appears on two lines -- this is an artifact of the 1401 presentation; in fact, only one line is used. 1403 If a challenge is received, then the client responds and awaits 1404 another reply, e.g., 1406 C: MSG 1 0 . 0 85 1407 C: Content-Type: text/xml 1408 C: 1409 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n 1410 C: END 1411 C: 1412 S: RPY 1 0 . 0 54 1413 S: Content-Type: text/xml 1414 S: 1415 S: 1416 S: END 1417 S: 1419 Of course, the client could abort the authentication process by 1420 sending "" instead. 1422 Alternatively, the server might reject the response with an error: 1423 e.g., 1425 C: MSG 1 0 . 0 85 1426 C: Content-Type: text/xml 1427 C: 1428 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n 1429 C: END 1430 C: 1431 S: ERR 1 1 . 0 48 1432 S: Content-Type: text/xml 1433 S: 1434 S: 1435 S: END 1436 S: 1438 Finally, depending on the SASL mechanism, an initialization element 1439 may be exchanged unidirectionally during channel creation, e.g., 1441 C: MSG 0 1 . 40 133 1442 C: Content-Type: text/xml 1443 C: 1444 C: 1445 C: 1447 C: 1448 C: END 1449 C: 1450 S: RPY 0 1 . 252 173 1451 S: Content-Type: text/xml 1452 S: 1453 S: 1454 S: PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+ 1455 1456 S: 1457 S: END 1458 S: 1460 Note that this example implies that the "blob" element in the 1461 server's reply appears on two lines -- this is an artifact of the 1462 presentation; in fact, only one line is used. 1464 4.1.2 Message Syntax 1466 Section 7.3 defines the messages that are used for each profile in 1467 the SASL family. 1469 Note that because many SASL mechanisms exchange binary data, the 1470 content of the "blob" element is always a base64-encoded string. 1472 4.1.3 Message Semantics 1474 The "blob" element has an optional "status" attribute, and arbitrary 1475 octets as its content: 1477 o the "status" attribute, if present, takes one of three values: 1479 abort: used by a client to indicate that it is aborting the 1480 authentication process; 1482 complete: used by a server to indicate that the exchange is 1483 complete and successful; or, 1485 continue: used by either a client or server, otherwise. 1487 Finally, note that SASL's EXTERNAL mechanism works with an "external 1488 authentication" service, which is provided by one of: 1490 o a transport security profile, capable of providing authentication 1491 information (e.g., Section 3.1), being active on the connection; 1493 o a network service, capable of providing strong authentication 1494 (e.g., IPSec[12]), underlying the connection; or, 1496 o a locally-defined security service. 1498 For authentication to succeed, two conditions must hold: 1500 o an external authentication service must be active; and, 1502 o if present, the authentication identity must be consistent with 1503 the credentials provided by the external authentication service 1504 (if the authentication identity is empty, then an authorization 1505 identity is automatically derived from the credentials provided 1506 by the external authentication service). 1508 5. Registration Templates 1510 5.1 Profile Registration Template 1512 When a profile is registered, the following information is supplied: 1514 Profile Identification: specify a URI[10] that authoritatively 1515 identifies this profile. 1517 Message Exchanged during Channel Creation: specify the datatypes 1518 that may be exchanged during channel creation. 1520 Messages starting one-to-one exchanges: specify the datatypes that 1521 may be present when an exchange starts. 1523 Messages in positive replies: specify the datatypes that may be 1524 present in a positive reply. 1526 Messages in negative replies: specify the datatypes that may be 1527 present in a negative reply. 1529 Messages in one-to-many exchanges: specify the datatypes that may be 1530 present in a one-to-many exchange. 1532 Message Syntax: specify the syntax of the datatypes exchanged by the 1533 profile. 1535 Message Semantics: specify the semantics of the datatypes exchanged 1536 by the profile. 1538 Contact Information: specify the postal and electronic contact 1539 information for the author of the profile. 1541 5.2 Feature Registration Template 1543 When a feature for the channel management profile is registered, the 1544 following information is supplied: 1546 Feature Identification: specify a string that identifies this 1547 feature. Unless the feature is registered with the IANA, the 1548 feature's identification MUST start with "x-". 1550 Feature Semantics: specify the semantics of the feature. 1552 Contact Information: specify the postal and electronic contact 1553 information for the author of the feature. 1555 6. Initial Registrations 1557 6.1 Registration: BEEP Channel Management 1559 Profile Identification: not applicable 1561 Messages exchanged during Channel Creation: not applicable 1563 Messages starting one-to-one exchanges: "start" or "close" 1565 Messages in positive replies: "greeting", "profile", or "ok" 1567 Messages in negative replies: "error" 1569 Messages in one-to-many exchanges: none 1571 Message Syntax: c.f., Section 7.1 1573 Message Semantics: c.f., Section 2.3.1 1575 Contact Information: c.f., the "Author's Address" section of this 1576 memo 1578 6.2 Registration: TLS Transport Security Profile 1580 Profile Identification: http://xml.resource.org/profiles/TLS 1582 Messages exchanged during Channel Creation: "ready" 1584 Messages starting one-to-one exchanges: "ready" 1586 Messages in positive replies: "proceed" 1588 Messages in negative replies: "error" 1590 Messages in one-to-many exchanges: none 1592 Message Syntax: c.f., Section 7.2 1594 Message Semantics: c.f., Section 3.1.3 1596 Contact Information: c.f., the "Author's Address" section of this 1597 memo 1599 6.3 Registration: SASL Family of Profiles 1601 Profile Identification: 1602 http://xml.resource.org/profiles/sasl/MECHANISM, where 1603 "MECHANISM" is a token registered with the IANA[15] 1605 Messages exchanged during Channel Creation: "blob" 1607 Messages starting one-to-one exchanges: "blob" 1609 Messages in positive replies: "blob" 1611 Messages in negative replies: "error" 1613 Messages in one-to-many exchanges: none 1615 Message Syntax: c.f., Section 7.3 1617 Message Semantics: c.f., Section 4.1.3 1619 Contact Information: c.f., the "Author's Address" section of this 1620 memo 1622 7. DTDs 1624 7.1 BEEP Channel Management DTD 1626 1636 1660 1661 1662 1663 1664 1665 1666 1678 1679 1683 1684 1688 1689 1690 1694 1695 1700 1702 1703 1707 7.2 TLS Transport Security Profile DTD 1709 1719 1727 1728 1731 1733 7.3 SASL Family of Profiles DTD 1735 1745 1753 1754 1760 8. Reply Codes 1762 code meaning 1763 ==== ======= 1764 421 service not available 1766 450 requested action not taken 1767 (e.g., lock already in use) 1769 451 requested action aborted 1770 (e.g., local error in processing) 1772 454 temporary authentication failure 1774 500 general syntax error 1775 (e.g., poorly-formed XML) 1777 501 syntax error in parameters 1778 (e.g., non-valid XML) 1780 504 parameter not implemented 1782 530 authentication required 1784 534 authentication mechanism insufficient 1785 (e.g., too weak, sequence exhausted, etc.) 1787 535 authentication failure 1789 537 action not authorized for user 1791 538 authentication mechanism requires encryption 1793 550 requested action not taken 1794 (e.g., no requested profiles are acceptable) 1796 553 parameter invalid 1798 554 transaction failed 1799 (e.g., policy violation) 1801 9. Security Considerations 1803 The BEEP framing mechanism, per se, provides no protection against 1804 attack; however, judicious use of initial tuning profiles provides 1805 varying degrees of assurance: 1807 1. If one of the profiles from the SASL family is used, refer to 1808 [5]'s Section 9 for a discussion of security considerations. 1810 2. If the TLS transport security profile is used (or if a SASL 1811 security layer is negotiated), then: 1813 1. A man-in-the-middle may remove the security-related profiles 1814 from the BEEP greeting or generate a negative reply to the 1815 "ready" element of the TLS transport security profile. A 1816 BEEP peer may be configurable to refuse to proceed without 1817 an acceptable level of privacy. 1819 2. A man-in-the-middle may cause a down-negotiation to the 1820 weakest cipher suite available. A BEEP peer should be 1821 configurable to refuse weak cipher suites. 1823 3. A man-in-the-middle may modify any protocol exchanges prior 1824 to a successful negotiation. Upon completing the 1825 negotiation, a BEEP peer must discard previously cached 1826 information about the BEEP session. 1828 As different TLS ciphersuites provide varying levels of 1829 security, administrators should carefully choose which 1830 ciphersuites are provisioned. 1832 As BEEP is peer-to-peer in nature, before performing any task 1833 associated with a message, each channel should apply the appropriate 1834 access control based on the authenticated identity and privacy level 1835 associated with the BEEP session. 1837 10. IANA Considerations 1839 The IANA registers "beep" as a GSSAPI[13] service name, as specified 1840 in Section 4.1. 1842 The IANA maintains a list of: 1844 o BEEP profiles, c.f., Section 5.1; and, 1846 o features for the channel management profile, c.f., Section 5.2. 1848 The IANA makes the registrations specified in Section 6.2 and 1849 Section 6.3. It is recommended that the IANA register these profiles 1850 using the IANA as a URI-prefix, and populate those URIs with the 1851 respective profile registrations. 1853 References 1855 [1] Rose, M.T., "On the Design of Application Protocols", 1856 draft-mrose-beep-design-00 (work in progress), July 2000. 1858 [2] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1859 Extensions (MIME) Part One: Format of Internet Message 1860 Bodies", RFC 2045, November 1996. 1862 [3] World Wide Web Consortium, "Extensible Markup Language (XML) 1863 1.0", W3C XML, February 1998, 1864 . 1866 [4] Dierks, T., Allen, C., Treese, W., Karlton, P. L., Freier, A. 1867 O. and P. C. Kocher, "The TLS Protocol Version 1.0", RFC 2246, 1868 January 1999. 1870 [5] Myers, J.G., "Simple Authentication and Security Layer 1871 (SASL)", RFC 2222, October 1997. 1873 [6] Rose, M.T., "Mapping the BEEP Framework onto TCP", 1874 draft-ietf-beep-tcpmapping-02 (work in progress), September 1875 2000. 1877 [7] Postel, J., "Transmission Control Protocol", RFC 793, STD 7, 1878 Sep 1981. 1880 [8] Crocker, D. H. and P. Overell, "Augmented BNF for Syntax 1881 Specifications: ABNF", RFC 2234, November 1997. 1883 [9] Alvestrand, H., "Tags for the Identification of Languages", 1884 RFC 1766, March 1995. 1886 [10] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform 1887 Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1888 1998. 1890 [11] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444, 1891 October 1998. 1893 [12] Kent, S. and R. Atkinson, "Security Architecture for the 1894 Internet Protocol", RFC 2401, November 1998. 1896 [13] Linn, J., "Generic Security Service Application Program 1897 Interface, Version 2", RFC 2078, January 1997. 1899 [14] 1902 [15] 1904 Author's Address 1906 Marshall T. Rose 1907 Invisible Worlds, Inc. 1908 1179 North McDowell Boulevard 1909 Petaluma, CA 94954-6559 1910 US 1912 Phone: +1 707 789 3700 1913 EMail: mrose@invisible.net 1914 URI: http://invisible.net/ 1916 Appendix A. Changes from draft-ietf-beep-framework-01 1918 o s/BXXP/BEEP/g 1920 o The default "Content-Type:" is now "application/octet-stream". 1922 o Initialization messages are now character data, not XML elements. 1924 o A template is provided for channel management feature 1925 registration (c.f., Section 5.2). 1927 Appendix B. Changes from draft-ietf-beep-framework-00 1929 o The names of messages are renamed: 1931 * "REQ" messages are now "MSG" messages; and, 1933 * "RSP" messages are now "RPY" (positive), "ANS"/"NULL" 1934 (one-to-many), and "ERR" (negative). 1936 o One-to-many exchanges are supported using the "ANS" message. 1938 o Commonly-used paraemters are re-ordered in the header: 1940 * channel numbers appear in each frame (and are 31-bits wide); 1941 and, 1943 * serial numbers are now message numbers, and are per-channel. 1945 o MIME "entity-headers" are now part of the payload (and there is 1946 no longer any header-related processing associated with them). 1948 o An IANA registration for BEEP error codes is no longer required 1949 (the error codes are used only within this specification). 1951 o The close message (Section 2.3.1.3) is also used to release the 1952 BEEP session. 1954 Appendix C. Changes from draft-mrose-bxxp-framework-01 1956 o Channel numbers are now 31-bits wide (instead of 8-bits). 1958 o Peers should support at least 257 concurrent channels. 1960 o The consistency rules in Section 2.2.1.1 now mandate that any 1961 MIME entity-headers occur only in the first frame of a message. 1963 o Discussion of the role of the entity-headers is moved to Section 1964 2.2.1.1. 1966 o Section 2.2.2 requires that a BEEP peer close a channel when a 1967 poorly-formed reply is received (unless it's channel zero, in 1968 which case the BEEP session is terminated). 1970 o Section 2.2.2 explains that in an XML-based profile, if something 1971 other than UTF-8 is sent, then a "Content-Type:" entity-header 1972 must be present to specify the character set. 1974 o The close (Section 2.3.1.3) and ok (Section 2.3.1.4) messages 1975 were added. 1977 o Both Section 2.3.1.3 and Section 2.3.1.5 clarify that diagnostic 1978 text is not to be interpreted by programs. 1980 o Section 5.1 limits the the size of an initialization element to 1981 4K octets. 1983 Appendix D. Changes from draft-mrose-bxxp-framework-00 1985 o The IPR notice is changed to be in full conformance with all 1986 provisions of Section 10 of RFC2026. 1988 o At the beginning of Section 2.2 (and in the ABNF in Section 1989 2.2.1) the relationship between messages and frames is clarified. 1991 o A typo involving the final CR LF in the ABNF in Section 2.2.1 is 1992 corrected. 1994 o In Section 2.2.1.1, the "contiguous message" rule replaces the 1995 "transport-specific" assertion (the sixth rule for identifying 1996 poorly-formed frames). 1998 o At the beginning of Section 2.3, an explanation of the 1999 relstionship between profiles and channels (and the greeting and 2000 start messages) is added. 2002 o In Section 2.3.1, the order of the sections for the greeting and 2003 start messages is reversed for readability. 2005 Appendix E. Acknowledgements 2007 The author gratefully acknowledges the contributions of: David 2008 Clark, Dave Crocker, Steve Deering, Marco Gazzetta, Danny Goodman, 2009 Steve Harris, Robert Herriot, Ken Hirsch, Greg Hudson, Ben Laurie, 2010 Carl Malamud, Michael Mealling, Keith McCloghrie, Paul Mockapetris, 2011 RL 'Bob' Morgan, Frank Morton, Darren New, Chris Newman, Joe Touch, 2012 Paul Vixie, Gabe Wachob, Daniel Woods, and, James Woodyatt. In 2013 particular, Dave Crocker provided helpful suggestions on the nature 2014 of segmentation in the framing mechanism. 2016 Full Copyright Statement 2018 Copyright (C) The Internet Society (2000). All Rights Reserved. 2020 This document and translations of it may be copied and furnished to 2021 others, and derivative works that comment on or otherwise explain it 2022 or assist in its implementation may be prepared, copied, published 2023 and distributed, in whole or in part, without restriction of any 2024 kind, provided that the above copyright notice and this paragraph 2025 are included on all such copies and derivative works. However, this 2026 document itself may not be modified in any way, such as by removing 2027 the copyright notice or references to the Internet Society or other 2028 Internet organizations, except as needed for the purpose of 2029 developing Internet standards in which case the procedures for 2030 copyrights defined in the Internet Standards process must be 2031 followed, or as required to translate it into languages other than 2032 English. 2034 The limited permissions granted above are perpetual and will not be 2035 revoked by the Internet Society or its successors or assigns. 2037 This document and the information contained herein is provided on an 2038 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 2039 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 2040 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 2041 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 2042 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2044 Acknowledgement 2046 Funding for the RFC editor function is currently provided by the 2047 Internet Society.