idnits 2.17.1 draft-ietf-beep-framework-03.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 1543: '...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 1666 has weird spacing: '...reeting err...' == Line 1757 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 (October 9, 2000) is 8599 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 1640 -- Looks like a reference, but probably isn't: 'RFC-1766' on line 1649 -- Looks like a reference, but probably isn't: '1-5' on line 1652 -- Looks like a reference, but probably isn't: '1-9' on line 1652 == Unused Reference: '10' is defined on line 1865, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. '2' ** Obsolete normative reference: RFC 2246 (ref. '3') (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2222 (ref. '4') (Obsoleted by RFC 4422, RFC 4752) == Outdated reference: A later version (-06) exists of draft-ietf-beep-tcpmapping-03 ** Obsolete normative reference: RFC 793 (ref. '6') (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 2234 (ref. '7') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 1766 (ref. '8') (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2396 (ref. '9') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2401 (ref. '11') (Obsoleted by RFC 4301) ** Obsolete normative reference: RFC 2078 (ref. '12') (Obsoleted by RFC 2743) -- Possible downref: Non-RFC (?) normative reference: ref. '13' -- Possible downref: Non-RFC (?) normative reference: ref. '14' Summary: 11 errors (**), 0 flaws (~~), 7 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: April 9, 2001 October 9, 2000 6 The Blocks Extensible Exchange Protocol Framework 7 draft-ietf-beep-framework-03 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 April 9, 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 References . . . . . . . . . . . . . . . . . . . . . . . . 53 101 Author's Address . . . . . . . . . . . . . . . . . . . . . 54 102 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 55 103 B. IANA Considerations . . . . . . . . . . . . . . . . . . . 56 104 Full Copyright Statement . . . . . . . . . . . . . . . . . 57 106 1. Introduction 108 This memo describes a generic application protocol framework for 109 connection-oriented, asynchronous interactions. 111 At the core of the BEEP framework is a framing mechanism that 112 permits simultaneous and independent exchanges of messages between 113 peers. Messages are arbitrary MIME[1] content, but are usually 114 textual (structured using XML[2]). 116 All exchanges occur in the context of a channel -- a binding to a 117 well-defined aspect of the application, such as transport security, 118 user authentication, or data exchange. 120 Each channel has an associated "profile" that defines the syntax and 121 semantics of the messages exchanged. Implicit in the operation of 122 BEEP is the notion of channel management. In addition to defining 123 BEEP's channel management profile, this document defines: 125 o the TLS[3] transport security profile; and, 127 o the SASL[4] family of profiles. 129 Other profiles, such as those used for data exchange, are defined by 130 an application protocol designer. 132 2. The BEEP Framework 134 A BEEP session is mapped onto an underlying transport service. A 135 separate series of documents describe how a particular transport 136 service realizes a BEEP session. For example, [5] describes how a 137 BEEP session is mapped onto a single TCP[6] connection. 139 When a session is established, each BEEP peer advertises the profile 140 it supports. Later on, during the creation of a channel, the client 141 supplies one or more proposed profiles for that channel. If the 142 server creates the channel, it selects one of the profiles and sends 143 it in a reply; otherwise, it may indicate that none of the profiles 144 are acceptable, and decline creation of the channel. 146 Channel usage falls into one of two categories: 148 initial tuning: these are used by profiles that perform 149 initialization once the BEEP session is established (e.g., 150 negotiating the use of transport security); although several 151 exchanges may be required to perform the initialization, these 152 channels become inactive early in the BEEP session and remain so 153 for the duration. 155 continuous: these are used by profiles that support data exchange; 156 typically, these channels are created after the initial tuning 157 channels have gone quiet. 159 2.1 Roles 161 Although BEEP is peer-to-peer, it is convenient to label each peer 162 in the context of the role it is performing at a given time: 164 o When a BEEP session is established, the peer that awaits new 165 connections is acting in the listening role, and the other peer, 166 which establishes a connection to the listener, is acting in the 167 initiating role. In the examples which follow, these are referred 168 to as "L:" and "I:", respectively. 170 o A BEEP peer starting an exchange is termed the client; similarly, 171 the other BEEP peer is termed the server. In the examples which 172 follow, these are referred to as "C:" and "S:", respectively. 174 Typically, a BEEP peer acting in the server role is also acting in a 175 listening role. However, because BEEP is peer-to-peer in nature, no 176 such requirement exists. 178 2.1.1 Exchange Styles 180 BEEP allows three styles of exchange: 182 MSG/RPY: the client sends a "MSG" message asking the server to 183 perform some task, the server performs the task and replies with 184 a "RPY" message (termed a positive reply). 186 MSG/ERR: the client sends a "MSG" message, the server does not 187 perform any task and replies with an "ERR" message (termed a 188 negative reply). 190 MSG/ANS: the client sends a "MSG" message, the server, during the 191 course of performing some task, replies with zero or more "ANS" 192 messages, and, upon completion of the task, sends a "NUL" 193 message, which signifies the end of the reply. 195 The first two styles are termed one-to-one exchanges, whilst the 196 third style is termed a one-to-many exchange. 198 2.2 Messages and Frames 200 A message is structured according to the rules of MIME. Accordingly, 201 each message may begin with "entity-headers" (c.f., MIME[1]'s 202 Section 3). If none, or only some, of the "entity-headers" are 203 present: 205 o the default "Content-Type" is "application/octet-stream"; and, 207 o the default "Content-Transfer-Encoding" is "binary". 209 Normally, a message is sent in a single frame. However, it may be 210 convenient or necesary to segment a message into multiple frames 211 (e.g., if only part of a message is ready to be sent). 213 Each frame consists of a header, the payload, and a trailer. The 214 header and trailer are each represented using printable ASCII 215 characters and are terminated with a CRLF pair. Between the header 216 and the trailer is the payload, consisting of zero or more octets. 218 For example, here is a message contained in a single frame that 219 contains a payload of 119 octets spread over 5 lines (each line is 220 terminated with a CRLF pair): 222 C: MSG 0 1 . 40 120 223 C: Content-Type: text/xml 224 C: 225 C: 226 C: 227 C: 228 C: END 229 C: 231 In this example, note that the entire message is represented in a 232 single frame. 234 2.2.1 Frame Syntax 236 The ABNF[7] for a frame is: 238 frame = data / mapping 240 data = header payload trailer 242 header = msg / rpy / err / ans / nul 244 msg = "MSG" SP common CR LF 245 rpy = "RPY" SP common CR LF 246 ans = "ANS" SP common SP ansno CR LF 247 err = "ERR" SP common CR LF 248 nul = "NUL" SP common CR LF 250 common = channel SP msgno SP more SP seqno SP size 251 channel = 0..2147483647 252 msgno = 0..2147483647 253 more = "." / "*" 254 seqno = 0..4294967295 255 size = 0..2147483647 256 ansno = 0..2147483647 258 payload = *OCTET 260 trailer = "END" CR LF 262 mapping = ;; each transport mapping may define additional frames 264 2.2.1.1 Frame Header 266 The frame header consists of a three-character keyword (one of: 267 "MSG", "RPY", "ERR", "ANS", or "NUL"), followed by zero or more 268 parameters. A single space character (decimal code 32, " ") 269 separates each component. The header is terminated with a CRLF pair. 271 The channel number ("channel") must be a non-negative integer (in 272 the range 0..2147483647). 274 The message number ("msgno") must be a non-negative integer (in the 275 range 0..2147483647) and have a different value than all other "MSG" 276 messages for which a reply has not been completely received. 278 The continuation indicator ("more", one of: decimal code 42, "*", or 279 decimal code 46, ".") specifies whether this is the final frame of 280 the message: 282 intermediate ("*"): at least one other frame follows for the 283 message; or, 285 complete ("."): this frame completes the message. 287 The sequence number ("seqno") must be a non-negative integer (in the 288 range 0..4294967295) and specifies the sequence number of the first 289 octet in the payload, for the associated channel. 291 The payload size ("size") must be a non-negative integer (in the 292 range 0..2147483647) and specifies the exact number of octets in the 293 payload. (This does not include either the header or trailer.) 295 Note that a frame may have an empty payload, e.g., 297 S: RPY 0 1 * 287 20 298 S: ... 299 S: ... 300 S: END 301 S: 302 S: RPY 0 1 . 307 0 303 S: END 304 S: 306 The answer number ("ansno") must be a non-negative integer (in the 307 range 0..4294967295) and must have a different value than all other 308 answers in progress for the message being replied to. 310 There are two kinds of frames: data and mapping. each transport 311 mapping (c.f., Section 2.5) may define its own frames. For example, 312 [5] defines the SEQ frame. The remainder of this section discusses 313 data frames. 315 When a message is segmented and sent as several frames, those frames 316 must be sent sequentally, without any intervening frames from other 317 messages on the same channel. However, there are two exceptions: 318 first, no restriction is made with respect to the interleaving of 319 frames for other channels; and, second, in a one-to-many exchange, 320 multiple answers may be simultaneously in progress. Accordingly, 321 frames for "ANS" messages may be interleaved on the same channel -- 322 the answer number is used for collation, e.g., 324 S: ANS 1 0 * 0 20 0 325 S: ... 326 S: ... 327 S: END 328 S: 329 S: ANS 1 0 * 20 20 1 330 S: ... 331 S: ... 332 S: END 333 S: 334 S: ANS 1 0 . 40 10 0 335 S: ... 336 S: END 337 S: 339 which shows two "ANS" messages interleaved on channel 1 as part of a 340 reply to message number 0. Note that the sequence number is advanced 341 for each frame sent on the channel, and is independent of the 342 messages sent in those frames. 344 There are several rules for identifying poorly-formed frames: 346 o if the header doesn't start with "MSG", "RPY", "ERR", "ANS", or 347 "NUL"; 349 o if any of the parameters in the header cannot be determined or 350 are invalid (i.e., syntactically incorrect); 352 o if the value of the channel number doesn't refer to an existing 353 channel; 355 o if the header starts with "MSG", and the message number refers to 356 a "MSG" message that has been completely received but for which a 357 reply has not been completely sent; 359 o if the header doesn't start with "MSG", and refers to a message 360 number for which a reply has not been completely received; 362 o if the header doesn't start with "MSG", and refers to a message 363 number that has never been sent (except during session 364 establishment, c.f., Section 2.3.1.1); 366 o if the header starts with "MSG", "ERR", or "ANS", and refers to a 367 message number for which at least one other frame has been 368 received, and the three-character keyword starting this frame and 369 the immediately-previous received frame for this reply are not 370 identical; 372 o if the header starts with "NUL", and refers to a message number 373 for which at least one other frame has been received, and the 374 keyword of of the immediately-previous received frame for this 375 reply isn't "ANS"; 377 o if the continuation indicator of the previous frame received on 378 the same channel was intermediate ("*"), and its message number 379 isn't identical to this frame's message number; 381 o if the value of the sequence number doesn't correspond to the 382 expected value for the associated channel (c.f., Section 383 2.2.1.2); or, 385 o if the header starts with "NUL", and the continuation indicator 386 is intermediate ("*") or the payload size is non-zero. 388 If a frame is poorly-formed, then the session is terminated without 389 generating a response, and it is recommended that a diagnostic entry 390 be logged. 392 2.2.1.2 Frame Payload 394 The frame payload consists of zero or more octets. 396 Every payload octet sent in each direction on a channel has an 397 associated sequence number. Numbering of payload octets within a 398 frame is such that the first payload octet is the lowest numbered, 399 and the following payload octets are numbered consecutively. (When a 400 channel is created, the sequence number associated with the first 401 payload octet of the first frame is 0.) 403 The actual sequence number space is finite, though very large, 404 ranging from 0..4294967295 (2**32 - 1). Since the space is finite, 405 all arithmetic dealing with sequence numbers is performed modulo 406 2**32. This unsigned arithmetic preserves the relationship of 407 sequence numbers as they cycle from 2**32 - 1 to 0 again. 409 When receiving a frame, the sum of its sequence number and payload 410 size, modulo 4294967296 (2**32), gives the expected sequence number 411 associated with the first payload octet of the next frame received. 412 Accordingly, when receiving a frame if the sequence number isn't the 413 expected value for this channel, then the BEEP peers have lost 414 synchronization, then the session is terminated without generating a 415 response, and it is recommended that a diagnostic entry be logged. 417 2.2.1.3 Frame Trailer 419 The frame trailer consists of "END" followed by a CRLF pair. 421 When receiving a frame, if the characters immediately following the 422 payload don't correspond to a trailer, then the session is 423 terminated without generating a response, and it is recommended that 424 a diagnostic entry be logged. 426 2.2.2 Frame Semantics 428 The semantics of each message is channel-specific. Accordingly, the 429 profile associated with a channel must define: 431 o the initialization messages, if any, exchanged during channel 432 creation; 434 o the messages that may be exchanged in the payload of the channel; 435 and, 437 o the semantics of these messages. 439 A profile registration template (Section 5.1) organizes this 440 information. 442 2.2.2.1 Poorly-formed Messages 444 When defining the behavior of the profile, the template must specify 445 how poorly-formed "MSG" messages are replied to. For example, the 446 channel management profile sends a negative reply containing an 447 error message (c.f., Section 2.3.1.5). 449 If a poorly-formed reply is received on channel zero, the session is 450 terminated without generating a response, and it is recommended that 451 a diagnostic entry be logged. 453 If a poorly-formed reply is received on another channel, then the 454 channel must be closed using the procedure in Section 2.3.1.3. 456 2.2.2.2 XML-based Profiles 458 If a profile uses XML[2] to structure its messages, then only XML's 459 baseline facilities (as described in the XML 1.0 specification[2]) 460 are allowed. Additional XML facilities (e.g., namespaces) are made 461 available only by being explicitly permitted in a given profile's 462 specification. 464 In particular this limitation allows use of only the five predefined 465 general entities references ("&", "<", ">", "'", and 466 """) and numeric entity references in the messages exchanged. 468 Further, because the profile registration template defines the 469 messages exchanged over a channel, the XML documents exchanged in 470 each message needn't have either a "XML" declaration (e.g., ) or a "DOCTYPE" declaration (e.g., ). 472 All other XML 1.0 instructions (e.g., CDATA blocks, processing 473 instructions, and so on) are allowed. 475 Finally, because the "XML" declaration isn't present, the default 476 character set for XML-based profiles is UTF-8. If another character 477 set is desired, the "Content-Type" entity-header must indicate this. 479 2.3 Channel Management 481 When a BEEP session starts, only channel number zero is defined, 482 which is used for channel management. Section 6.1 contains the 483 profile registration for BEEP channel management. 485 Channel management allows each BEEP peer to advertise the profiles 486 that it supports (c.f., Section 2.3.1.1), bind an instance of one of 487 those profiles to a channel (c.f., Section 2.3.1.2), and then later 488 close any channels or release the BEEP session (c.f., Section 489 2.3.1.3). 491 A BEEP peer should support at least 257 concurrent channels. 493 2.3.1 Message Semantics 495 2.3.1.1 The Greeting Message 497 When a BEEP session is established, each BEEP peer signifies its 498 availability by immediately sending a positive reply with a message 499 number of zero that contains a "greeting" element, e.g., 501 L: 502 I: 503 L: RPY 0 0 . 0 110 504 L: Content-Type: text/xml 505 L: 506 L: 507 L: 508 L: 509 L: END 510 L: 511 I: RPY 0 0 . 0 40 512 I: Content-Type: text/xml 513 I: 514 I: 515 I: END 516 I: 518 Note that this example implies that the BEEP peer in the initiating 519 role waits until the BEEP peer in the listening role sends its 520 greeting -- this is an artifact of the presentation; in fact, both 521 BEEP peers send their replies independently. 523 The "greeting" element has two optional attributes ("features" and 524 "localize") and zero or more "profile" elements, one for each 525 profile supported by the BEEP peer acting in a server role: 527 o the "features" attribute, if present, contains one or more 528 feature tokens, each indicating an optional feature of the 529 channel management profile supported by the BEEP peer; 531 o the "localize" attribute, if present, contains one or more 532 language tokens (defined in [8]), each identifying a desirable 533 language tag to be used by the remote BEEP peer when generating 534 textual diagnostics for the "close" and "error" elements (the 535 tokens are ordered from most to least desirable); and, 537 o each "profile" element contained within the "greeting" element 538 identifies a profile, and unlike the "profile" elements that 539 occur within the "start" element, the content of each "profile" 540 element may not contain an optional initialization message. 542 At present, there are no optional features defined for the channel 543 management profile. 545 Section 5.2 defines a registration template for optional features. 547 2.3.1.2 The Start Message 549 When a BEEP peer wants to create a channel, it sends a "start" 550 element on channel zero, e.g., 552 C: MSG 0 1 . 40 120 553 C: Content-Type: text/xml 554 C: 555 C: 556 C: 557 C: 558 C: END 559 C: 561 The "start" element has a "number" attribute, an optional 562 "serverName" attribute, and one or more "profile" elements: 564 o the "number" attribute indicates the channel number (in the range 565 1..2147483647) used to identify the channel in future messages; 567 o the "serverName" attribute, an arbitrary string, indicates the 568 desired server name for this BEEP session; and, 570 o each "profile" element contained with the "start" element has a 571 "uri" attribute, an optional "encoding" attribute, and arbitrary 572 character data as content: 574 * the "uri" attribute authoritatively identifies the profile; 576 * the "encoding" attribute, if present, specifies whether the 577 content of the "profile" element is represented as a 578 base64-encoded string; and, 580 * the content of the "profile" element, if present, must be no 581 longer than 4K octets in length and specifies an 582 initialization message given to the channel as soon as it is 583 created. 585 To avoid conflict in assigning channel numbers when requesting the 586 creation of a channel, BEEP peers acting in the initiating role use 587 only positive integers that are odd-numbered; similarly, BEEP peers 588 acting in the listening role use only positive integers that are 589 even-numbered. 591 The "serverName" attribute for the first successful "start" element 592 received by a BEEP peer is meaningful for the duration of the BEEP 593 session. If present, the BEEP peer decides whether to operate as the 594 indicated "serverName"; if not, an "error" element is sent in a 595 negative reply. 597 When a BEEP peer receives a "start" element on channel zero, it 598 examines each of the proposed profiles, and decides whether to use 599 one of them to create the channel. If so, the appropriate "profile" 600 element is sent in a positive reply; otherwise, an "error" element 601 is sent in a negative reply. 603 When creating the channel, the value of the "serverName" attribute 604 from the first successful "start" element is consulted to provide 605 configuration information, e.g., the desired server-side certificate 606 when starting the TLS transport security profile (Section 3.1). 608 For example, a successful channel creation might look like this: 610 C: MSG 0 1 . 40 197 611 C: Content-Type: text/xml 612 C: 613 C: 614 C: 615 C: 617 C: 618 C: END 619 C: 620 S: RPY 0 1 . 252 87 621 S: Content-Type: text/xml 622 S: 623 S: 624 S: END 625 S: 627 Similarly, an unsuccessful channel creation might look like this: 629 C: MSG 0 1 . 40 120 630 C: Content-Type: text/xml 631 C: 632 C: 633 C: 634 C: 635 C: END 636 C: 637 S: ERR 0 1 . 252 115 638 S: Content-Type: text/xml 639 S: 640 S: number attribute 641 S: in <start> element must be odd-valued 642 S: END 643 S: 645 Finally, here's an example in which an initialization element is 646 exchanged during channel creation: 648 C: MSG 0 1 . 40 158 649 C: Content-Type: text/xml 650 C: 651 C: 652 C: 653 C: ]]> 654 C: 655 C: 656 C: END 657 C: 658 S: RPY 0 1 . 110 121 659 S: Content-Type: text/xml 660 S: 661 S: 662 S: ]]> 663 S: 664 S: END 665 S: 667 2.3.1.3 The Close Message 669 When a BEEP peer wants to close a channel, it sends a "close" 670 element on channel zero, e.g., 672 C: MSG 0 2 . 223 59 673 C: Content-Type: text/xml 674 C: 675 C: 676 C: END 677 C: 679 The "close" element has a "number" attribute, a "code" attribute, an 680 optional "xml:lang" attribute, and an optional textual diagnostic as 681 its content: 683 o the "number" attribute indicates the channel number; 685 o the "code" attribute is a three-digit reply code meaningful to 686 programs (c.f., Section 8); 688 o the "xml:lang" attribute identifies the language that the 689 element's content is written in (the value is suggested, but not 690 mandated, by the "localize" attribute of the "greeting" element 691 sent by the remote BEEP peer); and, 693 o the textual diagnostic (which may be multiline) is meaningful to 694 implementers, perhaps administrators, and possibly even users, 695 but never programs. 697 Note that if the textual diagnostic is present, then the "xml:lang" 698 attribute is absent only if the language indicated as the remote 699 BEEP peer's first choice is used. 701 If the value of the "number" attribute is zero, then the BEEP peer 702 wants to release the BEEP session (c.f., Section 2.4) -- otherwise 703 the value of the "number" attribute refers to an existing channel. 705 When a BEEP peer receives a "close" element on channel zero, it 706 decides whether it is willing to close the channel. If so, an "ok" 707 element is sent in a positive reply; otherwise, an "error" element 708 is sent in a negative reply. 710 For example, a successful channel close might look like this: 712 C: MSG 0 2 . 223 59 713 C: Content-Type: text/xml 714 C: 715 C: 716 C: END 717 C: 718 S: RPY 0 2 . 423 34 719 S: Content-Type: text/xml 720 S: 721 S: 722 S: END 723 S: 725 Similarly, an unsuccessful channel close might look like this: 727 C: MSG 0 2 . 223 59 728 C: Content-Type: text/xml 729 C: 730 C: 731 C: END 732 C: 733 S: ERR 0 2 . 423 67 734 S: Content-Type: text/xml 735 S: 736 S: still working 737 S: END 738 S: 740 2.3.1.4 The OK Message 742 When a BEEP peer agrees to close a channel (or release the BEEP 743 session), it sends an "ok" element in a positive reply. 745 The "ok" element has no attributes and no content. 747 2.3.1.5 The Error Message 749 When a BEEP peer declines the creation of a channel, it sends an 750 "error" element in a negative reply, e.g., 752 I: MSG 0 1 . 40 115 753 I: Content-Type: text/xml 754 I: 755 I: 756 I: 757 I: 758 I: END 759 I: 760 L: ERR 0 1 . 252 93 761 L: Content-Type: text/xml 762 L: 763 L: all requested profiles are 764 L: unsupported 765 L: END 766 L: 768 The "error" element has a "code" attribute, an optional "xml:lang" 769 attribute, and an optional textual diagnostic as its content: 771 o the "code" attribute is a three-digit reply code meaningful to 772 programs (c.f., Section 8); 774 o the "xml:lang" attribute identifies the language that the 775 element's content is written in (the value is suggested, but not 776 mandated, by the "localize" attribute of the "greeting" element 777 sent by the remote BEEP peer); and, 779 o the textual diagnostic (which may be multiline) is meaningful to 780 implementers, perhaps administrators, and possibly even users, 781 but never programs. 783 Note that if the textual diagnostic is present, then the "xml:lang" 784 attribute is absent only if the language indicated as the remote 785 BEEP peer's first choice is used. 787 In addition, a BEEP peer sends an "error" element whenever: 789 o it receives a "MSG" message containing a poorly-formed or 790 unexpected element; 792 o it receives a "MSG" message asking to close a channel (or release 793 the BEEP session) and it declines to do so; or 795 o a BEEP session is established, the BEEP peer is acting in the 796 listening role, and that BEEP peer is unavailable (in this case, 797 the BEEP acting in the listening role does not send a "greeting" 798 element). 800 In the final case, both BEEP peers terminate the session, and it is 801 recommended that a diagnostic entry be logged by both BEEP peers. 803 2.4 Session Establishment and Release 805 When a BEEP session is established, each BEEP peer signifies its 806 availability by immediately sending a positive reply with a message 807 number of zero on channel zero that contains a "greeting" element, 808 e.g., 810 L: 811 I: 812 L: RPY 0 0 . 0 110 813 L: Content-Type: text/xml 814 L: 815 L: 816 L: 817 L: 818 L: END 819 L: 820 I: RPY 0 0 . 0 40 821 I: Content-Type: text/xml 822 I: 823 I: 824 I: END 825 I: 827 Alternatively, if the BEEP peer acting in the listening role is 828 unavailable, it sends a negative reply, e.g., 830 L: 831 I: 832 L: ERR 0 0 . 0 48 833 L: Content-Type: text/xml 834 L: 835 L: 836 L: END 837 L: 838 I: RPY 0 0 . 0 40 839 I: Content-Type: text/xml 840 I: 841 I: 842 I: END 843 I: 844 I: 845 L: 846 L: 848 and the "greeting" element sent by the BEEP peer acting in the 849 initiating role is ignored. It is recommended that a diagnostic 850 entry be logged by both BEEP peers. 852 Note that both of these examples imply that the BEEP peer in the 853 initiating role waits until the BEEP peer in the listening role 854 sends its greeting -- this is an artifact of the presentation; in 855 fact, both BEEP peers send their replies independently. 857 When a BEEP peer wants to release the BEEP session, it sends a 858 "close" element with a zero-valued "number" attribute on channel 859 zero. The other BEEP peer indicates its willingness by sending an 860 "ok" element in a positive reply, e.g., 862 C: MSG 0 1 . 40 48 863 C: Content-Type: text/xml 864 C: 865 C: 866 C: END 867 C: 868 S: RPY 0 1 . 252 34 869 S: Content-Type: text/xml 870 S: 871 S: 872 S: END 873 S: 874 I: 875 L: 876 L: 878 Alternatively, if the other BEEP doesn't want to release the BEEP 879 session, the exchange might look like this: 881 C: MSG 0 1 . 40 48 882 C: Content-Type: text/xml 883 C: 884 C: 885 C: END 886 C: 887 S: ERR 0 1 . 252 67 888 S: Content-Type: text/xml 889 S: 890 S: still working 891 S: END 892 S: 894 If session release is declined, the BEEP session should not be 895 terminated, if possible. 897 2.5 Transport Mappings 899 All transport interactions occur in the context of a session -- a 900 mapping onto a particular transport service. Accordingly, this memo 901 defines the requirements that must be satisified by any document 902 describing how a particular transport service realizes a BEEP 903 session. 905 2.5.1 Session Management 907 A BEEP session is connection-oriented. A mapping document must 908 define: 910 o how a BEEP session is established; 912 o how a BEEP peer is identified as acting in the listening role; 914 o how a BEEP peer is identified as acting in the initiating role; 916 o how a BEEP session is released; and, 918 o how a BEEP session is terminated. 920 2.5.2 Message Exchange 922 A BEEP session is message-oriented. A mapping document must define: 924 o how messages are reliably sent and received; 926 o how messages on the same channel are received in the same order 927 as they were sent; and, 929 o how messages on different channels are sent without ordering 930 constraint. 932 2.6 Parallelism 934 2.6.1 Within a Single Channel 936 A BEEP peer acting in the client role may send multiple "MSG" 937 messages on the same channel without waiting to receive the 938 corresponding replies. 940 A BEEP peer acting in the server role must process all "MSG" 941 messages for a given channel in the same order as they are received. 942 As a consequence, the BEEP peer must generate replies in the same 943 order as the corresponding "MSG" messages are received on a given 944 channel. 946 2.6.2 Between Different Channels 948 A BEEP peer acting in the client role may send multiple "MSG" 949 messages on different channels without waiting to receive the 950 corresponding replies. 952 A BEEP peer acting in the server role may process "MSG" messages 953 received on different channels in any order it chooses. As a 954 consequence, although the replies for a given channel appear to be 955 generated in the same order in which the corresponding "MSG" 956 messages are received, there is no ordering constraint for replies 957 on different channels. 959 2.6.3 Pre-emptive Replies 961 A BEEP peer acting in the server role may send a negative reply 962 before it receives the final "MSG" frame of a message. If it does 963 so, that BEEP peer is obliged to ignore any subsequent "MSG" frames 964 for that message, up to and including the final "MSG" frame. 966 If a BEEP peer acting in the client role receives a negative reply 967 before it sends the final "MSG" frame for a message, then it is 968 required to send a "MSG" frame with a continuation status of 969 complete (".") and having a zero-length payload. 971 2.6.4 Interference 973 If the processing of a particular message has sequencing impacts on 974 other messages (either intra-channel or inter-channel), then the 975 corresponding profile should define this behavior, e.g., a profile 976 whose messages alter the underlying transport mapping. 978 2.7 Peer-to-Peer Behavior 980 BEEP is peer-to-peer -- as such both peers must be prepared to 981 receive all messages defined in this memo. Accordingly, an 982 initiating BEEP peer capable of acting only in the client role must 983 behave gracefully if it receives a "MSG" message. Accordingly, all 984 profiles must provide an appropriate error message for replying to 985 unexpected "MSG" messages. 987 As a consequence of the peer-to-peer nature of BEEP, message numbers 988 are unidirectionally-significant. That is, the message numbers in 989 "MSG" messages sent by a BEEP peer acting in the initiating role are 990 unrelated to the message numbers in "MSG" messages sent by a BEEP 991 peer acting in the listening role. 993 For example, these two messages 995 I: MSG 0 1 . 40 120 996 I: Content-Type: text/xml 997 I: 998 I: 999 I: 1000 I: 1001 I: END 1002 I: 1003 L: MSG 0 1 . 252 116 1004 L: Content-Type: text/xml 1005 L: 1006 L: 1007 L: 1008 L: 1009 L: END 1010 L: 1012 refer to different messages sent on channel zero. 1014 3. Transport Security 1016 When a BEEP session is established, plaintext transfer, without 1017 privacy, is provided. Accordingly, transport security in BEEP is 1018 achieved using an initial tuning profile. 1020 This document defines one profile: 1022 o the TLS transport security profile, based on TLS version one[3]. 1024 Other profiles may be defined and deployed on a bilateral basis. 1025 Note that because of their intimate relationship with the tranpsort 1026 service, a given transport security profile tends to be relevant to 1027 a single transort mapping (c.f., Section 2.5). 1029 When a channel associated with transport security begins the 1030 underlying negotiation process, all channels (including channel 1031 zero) are closed on the BEEP session. Accordingly, upon completion 1032 of the negotiation process, regardless of its outcome, a new 1033 greeting is issued by both BEEP peers. (If the negotiation process 1034 fails, then either BEEP peer may instead terminate the session, and 1035 it is recommended that a diagnostic entry be logged.) 1037 A BEEP peer may choose to issue different greetings based on whether 1038 privacy is in use, e.g., 1040 L: 1041 I: 1042 L: RPY 0 0 . 0 110 1043 L: Content-Type: text/xml 1044 L: 1045 L: 1046 L: 1047 L: 1048 L: END 1049 L: 1050 I: RPY 0 0 . 0 40 1051 I: Content-Type: text/xml 1052 I: 1053 I: 1054 I: END 1055 I: 1056 I: MSG 0 1 . 40 158 1057 I: Content-Type: text/xml 1058 I: 1059 I: 1060 I: 1061 I: ]]> 1062 I: 1063 I: 1064 I: END 1065 I: 1066 L: RPY 0 1 . 110 121 1067 L: Content-Type: text/xml 1068 L: 1069 L: 1070 L: ]]> 1071 L: 1072 L: END 1073 L: 1075 ... successful transport security negotiation ... 1077 L: RPY 0 0 . 0 252 1078 L: Content-Type: text/xml 1079 L: 1080 L: 1081 L: 1083 L: 1084 L: 1085 L: 1086 L: END 1087 L: 1088 I: RPY 0 0 . 0 40 1089 I: Content-Type: text/xml 1090 I: 1091 I: 1092 I: END 1093 I: 1095 Of course, not all BEEP peers need be as single-minded: 1097 L: 1098 I: 1099 L: RPY 0 0 . 0 311 1100 L: Content-Type: text/xml 1101 L: 1102 L: 1103 L: 1105 L: 1106 L: 1107 L: 1108 L: 1109 L: END 1110 L: 1111 I: RPY 0 0 . 0 40 1112 I: Content-Type: text/xml 1113 I: 1114 I: 1115 I: END 1116 I: 1117 I: MSG 0 1 . 40 158 1118 I: Content-Type: text/xml 1119 I: 1120 I: 1121 I: 1122 I: ]]> 1123 I: 1124 I: 1125 I: END 1126 I: 1127 L: RPY 0 1 . 311 121 1128 L: Content-Type: text/xml 1129 L: 1130 L: 1131 L: ]]> 1132 L: 1133 L: END 1134 L: 1136 ... failed transport security negotiation ... 1138 L: RPY 0 0 . 0 311 1139 L: Content-Type: text/xml 1140 L: 1141 L: 1142 L: 1144 L: 1145 L: 1146 L: 1147 L: 1148 L: END 1149 L: 1150 I: RPY 0 0 . 0 40 1151 I: Content-Type: text/xml 1152 I: 1153 I: 1154 I: END 1155 I: 1157 3.1 The TLS Transport Security Profile 1159 Section 6.2 contains the registration for this profile. 1161 3.1.1 Profile Identification and Initialization 1163 The TLS transport security profile is identified as: 1165 http://xml.resource.org/profiles/TLS 1167 in the BEEP "profile" element during channel creation. 1169 During channel creation, the corresponding "profile" element in the 1170 BEEP "start" element may contain a "ready" element. If channel 1171 creation is successful, then before sending the corresponding reply, 1172 the BEEP peer processes the "ready" element and includes the 1173 resulting response in the reply, e.g., 1175 C: MSG 0 1 . 40 158 1176 C: Content-Type: text/xml 1177 C: 1178 C: 1179 C: 1180 C: ]]> 1181 C: 1182 C: 1183 C: END 1184 C: 1185 S: RPY 0 1 . 110 121 1186 S: Content-Type: text/xml 1187 S: 1188 S: 1189 S: ]]> 1190 S: 1191 S: END 1192 S: 1194 Note that it is possible for the channel to be created, but for the 1195 encapsulated operation to fail, e.g., 1197 C: MSG 0 1 . 40 173 1198 C: Content-Type: text/xml 1199 C: 1200 C: 1201 C: 1202 C: ]]> 1203 C: 1204 C: 1205 C: END 1206 C: 1207 S: RPY 0 1 . 110 181 1208 S: Content-Type: text/xml 1209 S: 1210 S: 1211 S: version attribute 1212 S: poorly formed in <ready> element 1213 S: 1214 S: END 1215 S: 1217 In this case, a positive reply is sent (as channel creation 1218 succeeded), but the encapsulated response contains an indication as 1219 to why the operation failed. 1221 3.1.2 Message Syntax 1223 Section 7.2 defines the messages that are used in the TLS transport 1224 security profile. 1226 3.1.3 Message Semantics 1228 3.1.3.1 The Ready Message 1230 The "ready" element has an optional "version" attribute and no 1231 content: 1233 o the "version" element defines the earliest version of TLS 1234 acceptable for use. 1236 When a BEEP peer sends the "ready" element, it must not send any 1237 further traffic on any channel until a corresponding reply is 1238 received; similarly, before processing a "ready" element, the 1239 receiving BEEP peer waits until any pending replies have been 1240 generated and sent. 1242 3.1.3.2 The Proceed Message 1244 The "proceed" element has no attributes and no content. It is sent 1245 as a reply to the "ready" element. When a BEEP peer receives the 1246 "ready" element, it begins the underlying negotiation process for 1247 transport security. 1249 4. User Authentication 1251 When a BEEP session is established, anonymous access, without trace 1252 information, is provided. Accordingly, user authentication in BEEP 1253 is achieved using an initial tuning profile. 1255 This document defines a family of profiles based on SASL mechanisms: 1257 o each mechanism in the IANA SASL registry[13] has an associated 1258 profile. 1260 Other profiles may be defined and deployed on a bilateral basis. 1262 Whenever a successful authentication occurs, on any channel, the 1263 authenticated identity is updated for all existing and future 1264 channels on the BEEP session; further, no additional attempts at 1265 authentication are allowed. 1267 Note that regardless of transport security and user authentication, 1268 authorization is an internal matter for each BEEP peer. As such, 1269 each peer may choose to restrict the operations it allows based on 1270 the authentication credentials provided (i.e., unauthorized 1271 operations might be rejected with error code 530). 1273 4.1 The SASL Family of Profiles 1275 Section 6.3 contains the registration for this profile. 1277 Note that SASL may provide both user authentication and transport 1278 security. Once transport security is successfully negotiated for a 1279 BEEP session, then a SASL security layer must not be negotiated; 1280 similarly, once any SASL negotiation is successful, a transport 1281 security profile must not begin its underlying negotiation process. 1283 Section 4 of the SASL specification[4] requires the following 1284 information be supplied by a protocol definition: 1286 service name: "beep" 1288 initiation sequence: Creating a channel using a BEEP profile 1289 corresponding to a SASL mechanism starts the exchange. An 1290 optional parameter corresponding to the "initial response" sent 1291 by the client is carried within a "blob" element during channel 1292 creation. 1294 exchange sequence: "Challenges" and "responses" are carried in 1295 exchanges of the "blob" element. The "status" attribute of the 1296 "blob" element is used both by a server indicating a successful 1297 completion of the exchange, and a client aborting the exchange, 1298 The server indicates failure of the exchange by sending an 1299 "error" element. 1301 security layer negotiation: When a security layer starts 1302 negotiation, all channels (including channel zero) are closed on 1303 the BEEP session. Accordingly, upon completion of the negotiation 1304 process, regardless of its outcome, a new greeting is issued by 1305 both BEEP peers. 1307 If a security layer is successfully negotiated, it takes effect 1308 immediately following the message that concludes the server's 1309 successful completion reply. 1311 use of the authorization identity: This is made available to all 1312 channels for the duration of the BEEP session. 1314 4.1.1 Profile Identification and Initialization 1316 Each SASL mechanism registered with the IANA is identified as: 1318 http://xml.resource.org/profiles/sasl/MECHANISM 1320 where "MECHANISM" is the token assigned to that mechanism by the 1321 IANA. 1323 Note that during channel creation, a BEEP peer may provide multiple 1324 profiles to the remote peer, e.g., 1326 C: MSG 0 1 . 40 197 1327 C: Content-Type: text/xml 1328 C: 1329 C: 1330 C: 1332 C: 1333 C: 1334 C: END 1335 C: 1336 S: RPY 0 1 . 252 87 1337 S: Content-Type: text/xml 1338 S: 1339 S: 1340 S: END 1341 S: 1343 During channel creation, the corresponding "profile" element in the 1344 BEEP "start" element may contain a "blob" element. Note that it is 1345 possible for the channel to be created, but for the encapsulated 1346 operation to fail, e.g., 1348 C: MSG 0 1 . 40 183 1349 C: Content-Type: text/xml 1350 C: 1351 C: 1352 C: 1353 C: AGJsb2NrbWFzdGVy]]> 1354 C: 1355 C: 1356 C: END 1357 C: 1358 S: RPY 0 1 . 252 166 1359 S: Content-Type: text/xml 1360 S: 1361 S: 1362 S: authentication mechanism is 1363 S: too weak 1364 S: 1365 S: END 1366 S: 1368 In this case, a positive reply is sent (as channel creation 1369 succeeded), but the encapsulated response contains an indication as 1370 to why the operation failed. 1372 Otherwise, the server sends a challenge (or signifies success), e.g., 1374 C: MSG 0 1 . 40 183 1375 C: Content-Type: text/xml 1376 C: 1377 C: 1378 C: 1379 C: AGJsb2NrbWFzdGVy]]> 1380 C: 1381 C: 1382 C: END 1383 C: 1384 S: RPY 0 1 . 252 171 1385 S: Content-Type: text/xml 1386 S: 1387 S: 1388 S: b3RwLXNoYTEgOTk5NyBwaXh5bWlzYXM4NTgwNSBleHQ= 1389 ]]> 1390 S: 1391 S: END 1392 S: 1394 Note that this example implies that the "blob" element in the 1395 server's reply appears on two lines -- this is an artifact of the 1396 presentation; in fact, only one line is used. 1398 If a challenge is received, then the client responds and awaits 1399 another reply, e.g., 1401 C: MSG 1 0 . 0 85 1402 C: Content-Type: text/xml 1403 C: 1404 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n 1405 C: END 1406 C: 1407 S: RPY 1 0 . 0 54 1408 S: Content-Type: text/xml 1409 S: 1410 S: 1411 S: END 1412 S: 1414 Of course, the client could abort the authentication process by 1415 sending "" instead. 1417 Alternatively, the server might reject the response with an error: 1418 e.g., 1420 C: MSG 1 0 . 0 85 1421 C: Content-Type: text/xml 1422 C: 1423 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n 1424 C: END 1425 C: 1426 S: ERR 1 1 . 0 48 1427 S: Content-Type: text/xml 1428 S: 1429 S: 1430 S: END 1431 S: 1433 Finally, depending on the SASL mechanism, an initialization element 1434 may be exchanged unidirectionally during channel creation, e.g., 1436 C: MSG 0 1 . 40 133 1437 C: Content-Type: text/xml 1438 C: 1439 C: 1440 C: 1442 C: 1443 C: END 1444 C: 1445 S: RPY 0 1 . 252 173 1446 S: Content-Type: text/xml 1447 S: 1448 S: 1449 S: PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+ 1450 1451 S: 1452 S: END 1453 S: 1455 Note that this example implies that the "blob" element in the 1456 server's reply appears on two lines -- this is an artifact of the 1457 presentation; in fact, only one line is used. 1459 4.1.2 Message Syntax 1461 Section 7.3 defines the messages that are used for each profile in 1462 the SASL family. 1464 Note that because many SASL mechanisms exchange binary data, the 1465 content of the "blob" element is always a base64-encoded string. 1467 4.1.3 Message Semantics 1469 The "blob" element has an optional "status" attribute, and arbitrary 1470 octets as its content: 1472 o the "status" attribute, if present, takes one of three values: 1474 abort: used by a client to indicate that it is aborting the 1475 authentication process; 1477 complete: used by a server to indicate that the exchange is 1478 complete and successful; or, 1480 continue: used by either a client or server, otherwise. 1482 Finally, note that SASL's EXTERNAL mechanism works with an "external 1483 authentication" service, which is provided by one of: 1485 o a transport security profile, capable of providing authentication 1486 information (e.g., Section 3.1), being active on the connection; 1488 o a network service, capable of providing strong authentication 1489 (e.g., IPSec[11]), underlying the connection; or, 1491 o a locally-defined security service. 1493 For authentication to succeed, two conditions must hold: 1495 o an external authentication service must be active; and, 1497 o if present, the authentication identity must be consistent with 1498 the credentials provided by the external authentication service 1499 (if the authentication identity is empty, then an authorization 1500 identity is automatically derived from the credentials provided 1501 by the external authentication service). 1503 5. Registration Templates 1505 5.1 Profile Registration Template 1507 When a profile is registered, the following information is supplied: 1509 Profile Identification: specify a URI[9] that authoritatively 1510 identifies this profile. 1512 Message Exchanged during Channel Creation: specify the datatypes 1513 that may be exchanged during channel creation. 1515 Messages starting one-to-one exchanges: specify the datatypes that 1516 may be present when an exchange starts. 1518 Messages in positive replies: specify the datatypes that may be 1519 present in a positive reply. 1521 Messages in negative replies: specify the datatypes that may be 1522 present in a negative reply. 1524 Messages in one-to-many exchanges: specify the datatypes that may be 1525 present in a one-to-many exchange. 1527 Message Syntax: specify the syntax of the datatypes exchanged by the 1528 profile. 1530 Message Semantics: specify the semantics of the datatypes exchanged 1531 by the profile. 1533 Contact Information: specify the postal and electronic contact 1534 information for the author of the profile. 1536 5.2 Feature Registration Template 1538 When a feature for the channel management profile is registered, the 1539 following information is supplied: 1541 Feature Identification: specify a string that identifies this 1542 feature. Unless the feature is registered with the IANA, the 1543 feature's identification MUST start with "x-". 1545 Feature Semantics: specify the semantics of the feature. 1547 Contact Information: specify the postal and electronic contact 1548 information for the author of the feature. 1550 6. Initial Registrations 1552 6.1 Registration: BEEP Channel Management 1554 Profile Identification: not applicable 1556 Messages exchanged during Channel Creation: not applicable 1558 Messages starting one-to-one exchanges: "start" or "close" 1560 Messages in positive replies: "greeting", "profile", or "ok" 1562 Messages in negative replies: "error" 1564 Messages in one-to-many exchanges: none 1566 Message Syntax: c.f., Section 7.1 1568 Message Semantics: c.f., Section 2.3.1 1570 Contact Information: c.f., the "Author's Address" section of this 1571 memo 1573 6.2 Registration: TLS Transport Security Profile 1575 Profile Identification: http://xml.resource.org/profiles/TLS 1577 Messages exchanged during Channel Creation: "ready" 1579 Messages starting one-to-one exchanges: "ready" 1581 Messages in positive replies: "proceed" 1583 Messages in negative replies: "error" 1585 Messages in one-to-many exchanges: none 1587 Message Syntax: c.f., Section 7.2 1589 Message Semantics: c.f., Section 3.1.3 1591 Contact Information: c.f., the "Author's Address" section of this 1592 memo 1594 6.3 Registration: SASL Family of Profiles 1596 Profile Identification: 1597 http://xml.resource.org/profiles/sasl/MECHANISM, where 1598 "MECHANISM" is a token registered with the IANA[14] 1600 Messages exchanged during Channel Creation: "blob" 1602 Messages starting one-to-one exchanges: "blob" 1604 Messages in positive replies: "blob" 1606 Messages in negative replies: "error" 1608 Messages in one-to-many exchanges: none 1610 Message Syntax: c.f., Section 7.3 1612 Message Semantics: c.f., Section 4.1.3 1614 Contact Information: c.f., the "Author's Address" section of this 1615 memo 1617 7. DTDs 1619 7.1 BEEP Channel Management DTD 1621 1631 1655 1656 1657 1658 1659 1660 1661 1673 1674 1678 1679 1683 1684 1685 1689 1690 1695 1697 1698 1702 7.2 TLS Transport Security Profile DTD 1704 1714 1722 1723 1726 1728 7.3 SASL Family of Profiles DTD 1730 1740 1748 1749 1755 8. Reply Codes 1757 code meaning 1758 ==== ======= 1759 421 service not available 1761 450 requested action not taken 1762 (e.g., lock already in use) 1764 451 requested action aborted 1765 (e.g., local error in processing) 1767 454 temporary authentication failure 1769 500 general syntax error 1770 (e.g., poorly-formed XML) 1772 501 syntax error in parameters 1773 (e.g., non-valid XML) 1775 504 parameter not implemented 1777 530 authentication required 1779 534 authentication mechanism insufficient 1780 (e.g., too weak, sequence exhausted, etc.) 1782 535 authentication failure 1784 537 action not authorized for user 1786 538 authentication mechanism requires encryption 1788 550 requested action not taken 1789 (e.g., no requested profiles are acceptable) 1791 553 parameter invalid 1793 554 transaction failed 1794 (e.g., policy violation) 1796 9. Security Considerations 1798 The BEEP framing mechanism, per se, provides no protection against 1799 attack; however, judicious use of initial tuning profiles provides 1800 varying degrees of assurance: 1802 1. If one of the profiles from the SASL family is used, refer to 1803 [4]'s Section 9 for a discussion of security considerations. 1805 2. If the TLS transport security profile is used (or if a SASL 1806 security layer is negotiated), then: 1808 1. A man-in-the-middle may remove the security-related profiles 1809 from the BEEP greeting or generate a negative reply to the 1810 "ready" element of the TLS transport security profile. A 1811 BEEP peer may be configurable to refuse to proceed without 1812 an acceptable level of privacy. 1814 2. A man-in-the-middle may cause a down-negotiation to the 1815 weakest cipher suite available. A BEEP peer should be 1816 configurable to refuse weak cipher suites. 1818 3. A man-in-the-middle may modify any protocol exchanges prior 1819 to a successful negotiation. Upon completing the 1820 negotiation, a BEEP peer must discard previously cached 1821 information about the BEEP session. 1823 As different TLS ciphersuites provide varying levels of 1824 security, administrators should carefully choose which 1825 ciphersuites are provisioned. 1827 As BEEP is peer-to-peer in nature, before performing any task 1828 associated with a message, each channel should apply the appropriate 1829 access control based on the authenticated identity and privacy level 1830 associated with the BEEP session. 1832 References 1834 [1] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1835 Extensions (MIME) Part One: Format of Internet Message 1836 Bodies", RFC 2045, November 1996. 1838 [2] World Wide Web Consortium, "Extensible Markup Language (XML) 1839 1.0", W3C XML, February 1998, 1840 . 1842 [3] Dierks, T., Allen, C., Treese, W., Karlton, P. L., Freier, A. 1843 O. and P. C. Kocher, "The TLS Protocol Version 1.0", RFC 2246, 1844 January 1999. 1846 [4] Myers, J.G., "Simple Authentication and Security Layer 1847 (SASL)", RFC 2222, October 1997. 1849 [5] Rose, M.T., "Mapping the BEEP Framework onto TCP", 1850 draft-ietf-beep-tcpmapping-03 (work in progress), October 2000. 1852 [6] Postel, J., "Transmission Control Protocol", RFC 793, STD 7, 1853 Sep 1981. 1855 [7] Crocker, D. H. and P. Overell, "Augmented BNF for Syntax 1856 Specifications: ABNF", RFC 2234, November 1997. 1858 [8] Alvestrand, H., "Tags for the Identification of Languages", 1859 RFC 1766, March 1995. 1861 [9] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform 1862 Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1863 1998. 1865 [10] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444, 1866 October 1998. 1868 [11] Kent, S. and R. Atkinson, "Security Architecture for the 1869 Internet Protocol", RFC 2401, November 1998. 1871 [12] Linn, J., "Generic Security Service Application Program 1872 Interface, Version 2", RFC 2078, January 1997. 1874 [13] 1877 [14] 1879 Author's Address 1881 Marshall T. Rose 1882 Invisible Worlds, Inc. 1883 1179 North McDowell Boulevard 1884 Petaluma, CA 94954-6559 1885 US 1887 Phone: +1 707 789 3700 1888 EMail: mrose@invisible.net 1889 URI: http://invisible.net/ 1891 Appendix A. Acknowledgements 1893 The author gratefully acknowledges the contributions of: David 1894 Clark, Dave Crocker, Steve Deering, Wesley Michael Eddy, Marco 1895 Gazzetta, Danny Goodman, Steve Harris, Robert Herriot, Ken Hirsch, 1896 Greg Hudson, Ben Laurie, Carl Malamud, Michael Mealling, Keith 1897 McCloghrie, Paul Mockapetris, RL 'Bob' Morgan, Frank Morton, Darren 1898 New, Chris Newman, Joe Touch, Paul Vixie, Gabe Wachob, Daniel Woods, 1899 and, James Woodyatt. In particular, Dave Crocker provided helpful 1900 suggestions on the nature of segmentation in the framing mechanism. 1902 Appendix B. IANA Considerations 1904 The IANA registers "beep" as a GSSAPI[12] service name, as specified 1905 in Section 4.1. 1907 The IANA maintains a list of: 1909 o BEEP profiles, c.f., Section 5.1; and, 1911 o features for the channel management profile, c.f., Section 5.2. 1913 The IANA makes the registrations specified in Section 6.2 and 1914 Section 6.3. It is recommended that the IANA register these profiles 1915 using the IANA as a URI-prefix, and populate those URIs with the 1916 respective profile registrations. 1918 Full Copyright Statement 1920 Copyright (C) The Internet Society (2000). All Rights Reserved. 1922 This document and translations of it may be copied and furnished to 1923 others, and derivative works that comment on or otherwise explain it 1924 or assist in its implementation may be prepared, copied, published 1925 and distributed, in whole or in part, without restriction of any 1926 kind, provided that the above copyright notice and this paragraph 1927 are included on all such copies and derivative works. However, this 1928 document itself may not be modified in any way, such as by removing 1929 the copyright notice or references to the Internet Society or other 1930 Internet organizations, except as needed for the purpose of 1931 developing Internet standards in which case the procedures for 1932 copyrights defined in the Internet Standards process must be 1933 followed, or as required to translate it into languages other than 1934 English. 1936 The limited permissions granted above are perpetual and will not be 1937 revoked by the Internet Society or its successors or assigns. 1939 This document and the information contained herein is provided on an 1940 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1941 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1942 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1943 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1944 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1946 Acknowledgement 1948 Funding for the RFC editor function is currently provided by the 1949 Internet Society.