idnits 2.17.1 draft-ietf-beep-framework-09.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 3 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 1642 has weird spacing: '...reeting err...' == Line 1733 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 (December 16, 2000) is 8529 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 1616 -- Looks like a reference, but probably isn't: 'RFC-1766' on line 1622 -- Looks like a reference, but probably isn't: '1-5' on line 1628 -- Looks like a reference, but probably isn't: '0-9' on line 1628 == Unused Reference: '11' is defined on line 1847, but no explicit reference was found in the text == Unused Reference: '13' is defined on line 1853, 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-05 ** 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. '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 2279 (ref. '13') (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 2078 (ref. '14') (Obsoleted by RFC 2743) -- Possible downref: Non-RFC (?) normative reference: ref. '15' -- Possible downref: Non-RFC (?) normative reference: ref. '16' Summary: 11 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: June 16, 2001 December 16, 2000 6 The Blocks Extensible Exchange Protocol Framework 7 draft-ietf-beep-framework-09 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 June 16, 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.3 Channel Management . . . . . . . . . . . . . . . . . . . . 15 58 2.3.1 Message Semantics . . . . . . . . . . . . . . . . . . . . 16 59 2.3.1.1 The Greeting Message . . . . . . . . . . . . . . . . . . . 16 60 2.3.1.2 The Start Message . . . . . . . . . . . . . . . . . . . . 17 61 2.3.1.3 The Close Message . . . . . . . . . . . . . . . . . . . . 20 62 2.3.1.4 The OK Message . . . . . . . . . . . . . . . . . . . . . . 22 63 2.3.1.5 The Error Message . . . . . . . . . . . . . . . . . . . . 22 64 2.4 Session Establishment and Release . . . . . . . . . . . . 24 65 2.5 Transport Mappings . . . . . . . . . . . . . . . . . . . . 26 66 2.5.1 Session Management . . . . . . . . . . . . . . . . . . . . 26 67 2.5.2 Message Exchange . . . . . . . . . . . . . . . . . . . . . 26 68 2.6 Parallelism . . . . . . . . . . . . . . . . . . . . . . . 27 69 2.6.1 Within a Single Channel . . . . . . . . . . . . . . . . . 27 70 2.6.2 Between Different Channels . . . . . . . . . . . . . . . . 27 71 2.6.3 Pre-emptive Replies . . . . . . . . . . . . . . . . . . . 27 72 2.6.4 Interference . . . . . . . . . . . . . . . . . . . . . . . 27 73 2.7 Peer-to-Peer Behavior . . . . . . . . . . . . . . . . . . 28 74 3. Transport Security . . . . . . . . . . . . . . . . . . . . 29 75 3.1 The TLS Transport Security Profile . . . . . . . . . . . . 32 76 3.1.1 Profile Identification and Initialization . . . . . . . . 32 77 3.1.2 Message Syntax . . . . . . . . . . . . . . . . . . . . . . 33 78 3.1.3 Message Semantics . . . . . . . . . . . . . . . . . . . . 34 79 3.1.3.1 The Ready Message . . . . . . . . . . . . . . . . . . . . 34 80 3.1.3.2 The Proceed Message . . . . . . . . . . . . . . . . . . . 34 81 4. User Authentication . . . . . . . . . . . . . . . . . . . 35 82 4.1 The SASL Family of Profiles . . . . . . . . . . . . . . . 36 83 4.1.1 Profile Identification and Initialization . . . . . . . . 37 84 4.1.2 Message Syntax . . . . . . . . . . . . . . . . . . . . . . 40 85 4.1.3 Message Semantics . . . . . . . . . . . . . . . . . . . . 41 86 5. Registration Templates . . . . . . . . . . . . . . . . . . 42 87 5.1 Profile Registration Template . . . . . . . . . . . . . . 42 88 5.2 Feature Registration Template . . . . . . . . . . . . . . 42 89 6. Initial Registrations . . . . . . . . . . . . . . . . . . 43 90 6.1 Registration: BEEP Channel Management . . . . . . . . . . 43 91 6.2 Registration: TLS Transport Security Profile . . . . . . . 43 92 6.3 Registration: SASL Family of Profiles . . . . . . . . . . 44 93 6.4 Registration: application/beep+xml . . . . . . . . . . . . 45 94 7. DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 95 7.1 BEEP Channel Management DTD . . . . . . . . . . . . . . . 46 96 7.2 TLS Transport Security Profile DTD . . . . . . . . . . . . 48 97 7.3 SASL Family of Profiles DTD . . . . . . . . . . . . . . . 49 98 8. Reply Codes . . . . . . . . . . . . . . . . . . . . . . . 50 99 9. Security Considerations . . . . . . . . . . . . . . . . . 51 100 References . . . . . . . . . . . . . . . . . . . . . . . . 52 101 Author's Address . . . . . . . . . . . . . . . . . . . . . 53 102 A. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 54 103 B. IANA Considerations . . . . . . . . . . . . . . . . . . . 55 104 Full Copyright Statement . . . . . . . . . . . . . . . . . 56 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 132 octets spread over 5 lines (each line is 220 terminated with a CRLF pair): 222 C: MSG 0 1 . 52 132 223 C: Content-Type: application/beep+xml 224 C: 225 C: 226 C: 227 C: 228 C: END 230 In this example, note that the entire message is represented in a 231 single frame. 233 2.2.1 Frame Syntax 235 The ABNF[7] for a frame is: 237 frame = data / mapping 239 data = header payload trailer 241 header = msg / rpy / err / ans / nul 243 msg = "MSG" SP common CR LF 244 rpy = "RPY" SP common CR LF 245 ans = "ANS" SP common SP ansno CR LF 246 err = "ERR" SP common CR LF 247 nul = "NUL" SP common CR LF 249 common = channel SP msgno SP more SP seqno SP size 250 channel = 0..2147483647 251 msgno = 0..2147483647 252 more = "." / "*" 253 seqno = 0..4294967295 254 size = 0..2147483647 255 ansno = 0..2147483647 257 payload = *OCTET 259 trailer = "END" CR LF 261 mapping = ;; each transport mapping may define additional frames 263 2.2.1.1 Frame Header 265 The frame header consists of a three-character keyword (one of: 266 "MSG", "RPY", "ERR", "ANS", or "NUL"), followed by zero or more 267 parameters. A single space character (decimal code 32, " ") 268 separates each component. The header is terminated with a CRLF pair. 270 The channel number ("channel") must be a non-negative integer (in 271 the range 0..2147483647). 273 The message number ("msgno") must be a non-negative integer (in the 274 range 0..2147483647) and have a different value than all other "MSG" 275 messages on the same channel for which a reply has not been 276 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 (c.f., Section 290 2.2.1.2). 292 The payload size ("size") must be a non-negative integer (in the 293 range 0..2147483647) and specifies the exact number of octets in the 294 payload. (This does not include either the header or trailer.) 296 Note that a frame may have an empty payload, e.g., 298 S: RPY 0 1 * 287 20 299 S: ... 300 S: ... 301 S: END 302 S: RPY 0 1 . 307 0 303 S: END 305 The answer number ("ansno") must be a non-negative integer (in the 306 range 0..4294967295) and must have a different value than all other 307 answers in progress for the message being replied to. 309 There are two kinds of frames: data and mapping. each transport 310 mapping (c.f., Section 2.5) may define its own frames. For example, 311 [5] defines the SEQ frame. The remainder of this section discusses 312 data frames. 314 When a message is segmented and sent as several frames, those frames 315 must be sent sequentally, without any intervening frames from other 316 messages on the same channel. However, there are two exceptions: 317 first, no restriction is made with respect to the interleaving of 318 frames for other channels; and, second, in a one-to-many exchange, 319 multiple answers may be simultaneously in progress. Accordingly, 320 frames for "ANS" messages may be interleaved on the same channel -- 321 the answer number is used for collation, e.g., 323 S: ANS 1 0 * 0 20 0 324 S: ... 325 S: ... 326 S: END 327 S: ANS 1 0 * 20 20 1 328 S: ... 329 S: ... 330 S: END 331 S: ANS 1 0 . 40 10 0 332 S: ... 333 S: END 335 which shows two "ANS" messages interleaved on channel 1 as part of a 336 reply to message number 0. Note that the sequence number is advanced 337 for each frame sent on the channel, and is independent of the 338 messages sent in those frames. 340 There are several rules for identifying poorly-formed frames: 342 o if the header doesn't start with "MSG", "RPY", "ERR", "ANS", or 343 "NUL"; 345 o if any of the parameters in the header cannot be determined or 346 are invalid (i.e., syntactically incorrect); 348 o if the value of the channel number doesn't refer to an existing 349 channel; 351 o if the header starts with "MSG", and the message number refers to 352 a "MSG" message that has been completely received but for which a 353 reply has not been completely sent; 355 o if the header doesn't start with "MSG", and refers to a message 356 number for which a reply has already been completely received; 358 o if the header doesn't start with "MSG", and refers to a message 359 number that has never been sent (except during session 360 establishment, c.f., Section 2.3.1.1); 362 o if the header starts with "MSG", "RPY", "ERR", or "ANS", and 363 refers to a message number for which at least one other frame has 364 been received, and the three-character keyword starting this 365 frame and the immediately-previous received frame for this 366 message number are not identical; 368 o if the header starts with "NUL", and refers to a message number 369 for which at least one other frame has been received, and the 370 keyword of of the immediately-previous received frame for this 371 reply isn't "ANS"; 373 o if the continuation indicator of the previous frame received on 374 the same channel was intermediate ("*"), and its message number 375 isn't identical to this frame's message number; 377 o if the value of the sequence number doesn't correspond to the 378 expected value for the associated channel (c.f., Section 379 2.2.1.2); or, 381 o if the header starts with "NUL", and the continuation indicator 382 is intermediate ("*") or the payload size is non-zero. 384 If a frame is poorly-formed, then the session is terminated without 385 generating a response, and it is recommended that a diagnostic entry 386 be logged. 388 2.2.1.2 Frame Payload 390 The frame payload consists of zero or more octets. 392 Every payload octet sent in each direction on a channel has an 393 associated sequence number. Numbering of payload octets within a 394 frame is such that the first payload octet is the lowest numbered, 395 and the following payload octets are numbered consecutively. (When a 396 channel is created, the sequence number associated with the first 397 payload octet of the first frame is 0.) 399 The actual sequence number space is finite, though very large, 400 ranging from 0..4294967295 (2**32 - 1). Since the space is finite, 401 all arithmetic dealing with sequence numbers is performed modulo 402 2**32. This unsigned arithmetic preserves the relationship of 403 sequence numbers as they cycle from 2**32 - 1 to 0 again. Consult 404 Sections 2 through 5 of [8] for a discussion of the arithmetic 405 properties of sequence numbers. 407 When receiving a frame, the sum of its sequence number and payload 408 size, modulo 4294967296 (2**32), gives the expected sequence number 409 associated with the first payload octet of the next frame received. 410 Accordingly, when receiving a frame if the sequence number isn't the 411 expected value for this channel, then the BEEP peers have lost 412 synchronization, then the session is terminated without generating a 413 response, and it is recommended that a diagnostic entry be logged. 415 2.2.1.3 Frame Trailer 417 The frame trailer consists of "END" followed by a CRLF pair. 419 When receiving a frame, if the characters immediately following the 420 payload don't correspond to a trailer, then the session is 421 terminated without generating a response, and it is recommended that 422 a diagnostic entry be logged. 424 2.2.2 Frame Semantics 426 The semantics of each message is channel-specific. Accordingly, the 427 profile associated with a channel must define: 429 o the initialization messages, if any, exchanged during channel 430 creation; 432 o the messages that may be exchanged in the payload of the channel; 433 and, 435 o the semantics of these messages. 437 A profile registration template (Section 5.1) organizes this 438 information. 440 2.2.2.1 Poorly-formed Messages 442 When defining the behavior of the profile, the template must specify 443 how poorly-formed "MSG" messages are replied to. For example, the 444 channel management profile sends a negative reply containing an 445 error message (c.f., Section 2.3.1.5). 447 If a poorly-formed reply is received on channel zero, the session is 448 terminated without generating a response, and it is recommended that 449 a diagnostic entry be logged. 451 If a poorly-formed reply is received on another channel, then the 452 channel must be closed using the procedure in Section 2.3.1.3. 454 2.3 Channel Management 456 When a BEEP session starts, only channel number zero is defined, 457 which is used for channel management. Section 6.1 contains the 458 profile registration for BEEP channel management. 460 Channel management allows each BEEP peer to advertise the profiles 461 that it supports (c.f., Section 2.3.1.1), bind an instance of one of 462 those profiles to a channel (c.f., Section 2.3.1.2), and then later 463 close any channels or release the BEEP session (c.f., Section 464 2.3.1.3). 466 A BEEP peer should support at least 257 concurrent channels. 468 2.3.1 Message Semantics 470 2.3.1.1 The Greeting Message 472 When a BEEP session is established, each BEEP peer signifies its 473 availability by immediately sending a positive reply with a message 474 number of zero that contains a "greeting" element, e.g., 476 L: 477 I: 478 L: RPY 0 0 . 0 122 479 L: Content-Type: application/beep+xml 480 L: 481 L: 482 L: 483 L: 484 L: END 485 I: RPY 0 0 . 0 52 486 I: Content-Type: application/beep+xml 487 I: 488 I: 489 I: END 491 Note that this example implies that the BEEP peer in the initiating 492 role waits until the BEEP peer in the listening role sends its 493 greeting -- this is an artifact of the presentation; in fact, both 494 BEEP peers send their replies independently. 496 The "greeting" element has two optional attributes ("features" and 497 "localize") and zero or more "profile" elements, one for each 498 profile supported by the BEEP peer acting in a server role: 500 o the "features" attribute, if present, contains one or more 501 feature tokens, each indicating an optional feature of the 502 channel management profile supported by the BEEP peer; 504 o the "localize" attribute, if present, contains one or more 505 language tokens (defined in [9]), each identifying a desirable 506 language tag to be used by the remote BEEP peer when generating 507 textual diagnostics for the "close" and "error" elements (the 508 tokens are ordered from most to least desirable); and, 510 o each "profile" element contained within the "greeting" element 511 identifies a profile, and unlike the "profile" elements that 512 occur within the "start" element, the content of each "profile" 513 element may not contain an optional initialization message. 515 Section 5.2 defines a registration template for optional features. 517 2.3.1.2 The Start Message 519 When a BEEP peer wants to create a channel, it sends a "start" 520 element on channel zero, e.g., 522 C: MSG 0 1 . 52 132 523 C: Content-Type: application/beep+xml 524 C: 525 C: 526 C: 527 C: 528 C: END 530 The "start" element has a "number" attribute, an optional 531 "serverName" attribute, and one or more "profile" elements: 533 o the "number" attribute indicates the channel number (in the range 534 1..2147483647) used to identify the channel in future messages; 536 o the "serverName" attribute, an arbitrary string, indicates the 537 desired server name for this BEEP session; and, 539 o each "profile" element contained with the "start" element has a 540 "uri" attribute, an optional "encoding" attribute, and arbitrary 541 character data as content: 543 * the "uri" attribute authoritatively identifies the profile; 545 * the "encoding" attribute, if present, specifies whether the 546 content of the "profile" element is represented as a 547 base64-encoded string; and, 549 * the content of the "profile" element, if present, must be no 550 longer than 4K octets in length and specifies an 551 initialization message given to the channel as soon as it is 552 created. 554 To avoid conflict in assigning channel numbers when requesting the 555 creation of a channel, BEEP peers acting in the initiating role use 556 only positive integers that are odd-numbered; similarly, BEEP peers 557 acting in the listening role use only positive integers that are 558 even-numbered. 560 The "serverName" attribute for the first successful "start" element 561 received by a BEEP peer is meaningful for the duration of the BEEP 562 session. If present, the BEEP peer decides whether to operate as the 563 indicated "serverName"; if not, an "error" element is sent in a 564 negative reply. 566 When a BEEP peer receives a "start" element on channel zero, it 567 examines each of the proposed profiles, and decides whether to use 568 one of them to create the channel. If so, the appropriate "profile" 569 element is sent in a positive reply; otherwise, an "error" element 570 is sent in a negative reply. 572 When creating the channel, the value of the "serverName" attribute 573 from the first successful "start" element is consulted to provide 574 configuration information, e.g., the desired server-side certificate 575 when starting the TLS transport security profile (Section 3.1). 577 For example, a successful channel creation might look like this: 579 C: MSG 0 1 . 52 209 580 C: Content-Type: application/beep+xml 581 C: 582 C: 583 C: 584 C: 586 C: 587 C: END 588 S: RPY 0 1 . 264 99 589 S: Content-Type: application/beep+xml 590 S: 591 S: 592 S: END 594 Similarly, an unsuccessful channel creation might look like this: 596 C: MSG 0 1 . 52 132 597 C: Content-Type: application/beep+xml 598 C: 599 C: 600 C: 601 C: 602 C: END 603 S: ERR 0 1 . 264 127 604 S: Content-Type: application/beep+xml 605 S: 606 S: number attribute 607 S: in <start> element must be odd-valued 608 S: END 610 Finally, here's an example in which an initialization element is 611 exchanged during channel creation: 613 C: MSG 0 1 . 52 170 614 C: Content-Type: application/beep+xml 615 C: 616 C: 617 C: 618 C: ]]> 619 C: 620 C: 621 C: END 622 S: RPY 0 1 . 122 133 623 S: Content-Type: application/beep+xml 624 S: 625 S: 626 S: ]]> 627 S: 628 S: END 630 2.3.1.3 The Close Message 632 When a BEEP peer wants to close a channel, it sends a "close" 633 element on channel zero, e.g., 635 C: MSG 0 2 . 247 71 636 C: Content-Type: application/beep+xml 637 C: 638 C: 639 C: END 641 The "close" element has a "number" attribute, a "code" attribute, an 642 optional "xml:lang" attribute, and an optional textual diagnostic as 643 its content: 645 o the "number" attribute indicates the channel number; 647 o the "code" attribute is a three-digit reply code meaningful to 648 programs (c.f., Section 8); 650 o the "xml:lang" attribute identifies the language that the 651 element's content is written in (the value is suggested, but not 652 mandated, by the "localize" attribute of the "greeting" element 653 sent by the remote BEEP peer); and, 655 o the textual diagnostic (which may be multiline) is meaningful to 656 implementers, perhaps administrators, and possibly even users, 657 but never programs. 659 Note that if the textual diagnostic is present, then the "xml:lang" 660 attribute is absent only if the language indicated as the remote 661 BEEP peer's first choice is used. 663 If the value of the "number" attribute is zero, then the BEEP peer 664 wants to release the BEEP session (c.f., Section 2.4) -- otherwise 665 the value of the "number" attribute refers to an existing channel. 667 When a BEEP peer receives a "close" element on channel zero, it 668 decides whether it is willing to close the channel. If so, an "ok" 669 element is sent in a positive reply; otherwise, an "error" element 670 is sent in a negative reply. 672 For example, a successful channel close might look like this: 674 C: MSG 0 2 . 247 71 675 C: Content-Type: application/beep+xml 676 C: 677 C: 678 C: END 679 S: RPY 0 2 . 447 46 680 S: Content-Type: application/beep+xml 681 S: 682 S: 683 S: END 685 Similarly, an unsuccessful channel close might look like this: 687 C: MSG 0 2 . 247 71 688 C: Content-Type: application/beep+xml 689 C: 690 C: 691 C: END 692 S: ERR 0 2 . 447 79 693 S: Content-Type: application/beep+xml 694 S: 695 S: still working 696 S: END 698 2.3.1.4 The OK Message 700 When a BEEP peer agrees to close a channel (or release the BEEP 701 session), it sends an "ok" element in a positive reply. 703 The "ok" element has no attributes and no content. 705 2.3.1.5 The Error Message 707 When a BEEP peer declines the creation of a channel, it sends an 708 "error" element in a negative reply, e.g., 710 I: MSG 0 1 . 52 127 711 I: Content-Type: application/beep+xml 712 I: 713 I: 714 I: 715 I: 716 I: END 717 L: ERR 0 1 . 264 105 718 L: Content-Type: application/beep+xml 719 L: 720 L: all requested profiles are 721 L: unsupported 722 L: END 724 The "error" element has a "code" attribute, an optional "xml:lang" 725 attribute, and an optional textual diagnostic as its content: 727 o the "code" attribute is a three-digit reply code meaningful to 728 programs (c.f., Section 8); 730 o the "xml:lang" attribute identifies the language that the 731 element's content is written in (the value is suggested, but not 732 mandated, by the "localize" attribute of the "greeting" element 733 sent by the remote BEEP peer); and, 735 o the textual diagnostic (which may be multiline) is meaningful to 736 implementers, perhaps administrators, and possibly even users, 737 but never programs. 739 Note that if the textual diagnostic is present, then the "xml:lang" 740 attribute is absent only if the language indicated as the remote 741 BEEP peer's first choice is used. 743 In addition, a BEEP peer sends an "error" element whenever: 745 o it receives a "MSG" message containing a poorly-formed or 746 unexpected element; 748 o it receives a "MSG" message asking to close a channel (or release 749 the BEEP session) and it declines to do so; or 751 o a BEEP session is established, the BEEP peer is acting in the 752 listening role, and that BEEP peer is unavailable (in this case, 753 the BEEP acting in the listening role does not send a "greeting" 754 element). 756 In the final case, both BEEP peers terminate the session, and it is 757 recommended that a diagnostic entry be logged by both BEEP peers. 759 2.4 Session Establishment and Release 761 When a BEEP session is established, each BEEP peer signifies its 762 availability by immediately sending a positive reply with a message 763 number of zero on channel zero that contains a "greeting" element, 764 e.g., 766 L: 767 I: 768 L: RPY 0 0 . 0 122 769 L: Content-Type: application/beep+xml 770 L: 771 L: 772 L: 773 L: 774 L: END 775 I: RPY 0 0 . 0 52 776 I: Content-Type: application/beep+xml 777 I: 778 I: 779 I: END 781 Alternatively, if the BEEP peer acting in the listening role is 782 unavailable, it sends a negative reply, e.g., 784 L: 785 I: 786 L: ERR 0 0 . 0 60 787 L: Content-Type: application/beep+xml 788 L: 789 L: 790 L: END 791 I: RPY 0 0 . 0 52 792 I: Content-Type: application/beep+xml 793 I: 794 I: 795 I: END 796 I: 797 L: 798 L: 800 and the "greeting" element sent by the BEEP peer acting in the 801 initiating role is ignored. It is recommended that a diagnostic 802 entry be logged by both BEEP peers. 804 Note that both of these examples imply that the BEEP peer in the 805 initiating role waits until the BEEP peer in the listening role 806 sends its greeting -- this is an artifact of the presentation; in 807 fact, both BEEP peers send their replies independently. 809 When a BEEP peer wants to release the BEEP session, it sends a 810 "close" element with a zero-valued "number" attribute on channel 811 zero. The other BEEP peer indicates its willingness by sending an 812 "ok" element in a positive reply, e.g., 814 C: MSG 0 1 . 52 60 815 C: Content-Type: application/beep+xml 816 C: 817 C: 818 C: END 819 S: RPY 0 1 . 264 46 820 S: Content-Type: application/beep+xml 821 S: 822 S: 823 S: END 824 I: 825 L: 826 L: 828 Alternatively, if the other BEEP doesn't want to release the BEEP 829 session, the exchange might look like this: 831 C: MSG 0 1 . 52 60 832 C: Content-Type: application/beep+xml 833 C: 834 C: 835 C: END 836 S: ERR 0 1 . 264 79 837 S: Content-Type: application/beep+xml 838 S: 839 S: still working 840 S: END 842 If session release is declined, the BEEP session should not be 843 terminated, if possible. 845 2.5 Transport Mappings 847 All transport interactions occur in the context of a session -- a 848 mapping onto a particular transport service. Accordingly, this memo 849 defines the requirements that must be satisified by any document 850 describing how a particular transport service realizes a BEEP 851 session. 853 2.5.1 Session Management 855 A BEEP session is connection-oriented. A mapping document must 856 define: 858 o how a BEEP session is established; 860 o how a BEEP peer is identified as acting in the listening role; 862 o how a BEEP peer is identified as acting in the initiating role; 864 o how a BEEP session is released; and, 866 o how a BEEP session is terminated. 868 2.5.2 Message Exchange 870 A BEEP session is message-oriented. A mapping document must define: 872 o how messages are reliably sent and received; 874 o how messages on the same channel are received in the same order 875 as they were sent; and, 877 o how messages on different channels are sent without ordering 878 constraint. 880 2.6 Parallelism 882 2.6.1 Within a Single Channel 884 A BEEP peer acting in the client role may send multiple "MSG" 885 messages on the same channel without waiting to receive the 886 corresponding replies. 888 A BEEP peer acting in the server role must process all "MSG" 889 messages for a given channel in the same order as they are received. 890 As a consequence, the BEEP peer must generate replies in the same 891 order as the corresponding "MSG" messages are received on a given 892 channel. 894 2.6.2 Between Different Channels 896 A BEEP peer acting in the client role may send multiple "MSG" 897 messages on different channels without waiting to receive the 898 corresponding replies. 900 A BEEP peer acting in the server role may process "MSG" messages 901 received on different channels in any order it chooses. As a 902 consequence, although the replies for a given channel appear to be 903 generated in the same order in which the corresponding "MSG" 904 messages are received, there is no ordering constraint for replies 905 on different channels. 907 2.6.3 Pre-emptive Replies 909 A BEEP peer acting in the server role may send a negative reply 910 before it receives the final "MSG" frame of a message. If it does 911 so, that BEEP peer is obliged to ignore any subsequent "MSG" frames 912 for that message, up to and including the final "MSG" frame. 914 If a BEEP peer acting in the client role receives a negative reply 915 before it sends the final "MSG" frame for a message, then it is 916 required to send a "MSG" frame with a continuation status of 917 complete (".") and having a zero-length payload. 919 2.6.4 Interference 921 If the processing of a particular message has sequencing impacts on 922 other messages (either intra-channel or inter-channel), then the 923 corresponding profile should define this behavior, e.g., a profile 924 whose messages alter the underlying transport mapping. 926 2.7 Peer-to-Peer Behavior 928 BEEP is peer-to-peer -- as such both peers must be prepared to 929 receive all messages defined in this memo. Accordingly, an 930 initiating BEEP peer capable of acting only in the client role must 931 behave gracefully if it receives a "MSG" message. Accordingly, all 932 profiles must provide an appropriate error message for replying to 933 unexpected "MSG" messages. 935 As a consequence of the peer-to-peer nature of BEEP, message numbers 936 are unidirectionally-significant. That is, the message numbers in 937 "MSG" messages sent by a BEEP peer acting in the initiating role are 938 unrelated to the message numbers in "MSG" messages sent by a BEEP 939 peer acting in the listening role. 941 For example, these two messages 943 I: MSG 0 1 . 52 132 944 I: Content-Type: application/beep+xml 945 I: 946 I: 947 I: 948 I: 949 I: END 950 L: MSG 0 1 . 264 128 951 L: Content-Type: application/beep+xml 952 L: 953 L: 954 L: 955 L: 956 L: END 958 refer to different messages sent on channel zero. 960 3. Transport Security 962 When a BEEP session is established, plaintext transfer, without 963 privacy, is provided. Accordingly, transport security in BEEP is 964 achieved using an initial tuning profile. 966 This document defines one profile: 968 o the TLS transport security profile, based on TLS version one[3]. 970 Other profiles may be defined and deployed on a bilateral basis. 971 Note that because of their intimate relationship with the transport 972 service, a given transport security profile tends to be relevant to 973 a single transport mapping (c.f., Section 2.5). 975 When a channel associated with transport security begins the 976 underlying negotiation process, all channels (including channel 977 zero) are closed on the BEEP session. Accordingly, upon completion 978 of the negotiation process, regardless of its outcome, a new 979 greeting is issued by both BEEP peers. (If the negotiation process 980 fails, then either BEEP peer may instead terminate the session, and 981 it is recommended that a diagnostic entry be logged.) 983 A BEEP peer may choose to issue different greetings based on whether 984 privacy is in use, e.g., 986 L: 987 I: 988 L: RPY 0 0 . 0 122 989 L: Content-Type: application/beep+xml 990 L: 991 L: 992 L: 993 L: 994 L: END 995 I: RPY 0 0 . 0 52 996 I: Content-Type: application/beep+xml 997 I: 998 I: 999 I: END 1000 I: MSG 0 1 . 52 170 1001 I: Content-Type: application/beep+xml 1002 I: 1003 I: 1004 I: 1005 I: ]]> 1006 I: 1007 I: 1008 I: END 1009 L: RPY 0 1 . 122 133 1010 L: Content-Type: application/beep+xml 1011 L: 1012 L: 1013 L: ]]> 1014 L: 1015 L: END 1017 ... successful transport security negotiation ... 1019 L: RPY 0 0 . 0 264 1020 L: Content-Type: application/beep+xml 1021 L: 1022 L: 1023 L: 1025 L: 1026 L: 1027 L: 1028 L: END 1029 I: RPY 0 0 . 0 52 1030 I: Content-Type: application/beep+xml 1031 I: 1032 I: 1033 I: END 1035 Of course, not all BEEP peers need be as single-minded: 1037 L: 1038 I: 1039 L: RPY 0 0 . 0 323 1040 L: Content-Type: application/beep+xml 1041 L: 1042 L: 1043 L: 1045 L: 1046 L: 1047 L: 1048 L: 1049 L: END 1050 I: RPY 0 0 . 0 52 1051 I: Content-Type: application/beep+xml 1052 I: 1053 I: 1054 I: END 1055 I: MSG 0 1 . 52 170 1056 I: Content-Type: application/beep+xml 1057 I: 1059 I: 1060 I: 1061 I: ]]> 1062 I: 1063 I: 1064 I: END 1065 L: RPY 0 1 . 323 133 1066 L: Content-Type: application/beep+xml 1067 L: 1068 L: 1069 L: ]]> 1070 L: 1071 L: END 1073 ... failed transport security negotiation ... 1075 L: RPY 0 0 . 0 323 1076 L: Content-Type: application/beep+xml 1077 L: 1078 L: 1079 L: 1081 L: 1082 L: 1083 L: 1084 L: 1085 L: END 1086 I: RPY 0 0 . 0 52 1087 I: Content-Type: application/beep+xml 1088 I: 1089 I: 1090 I: END 1092 3.1 The TLS Transport Security Profile 1094 Section 6.2 contains the registration for this profile. 1096 3.1.1 Profile Identification and Initialization 1098 The TLS transport security profile is identified as: 1100 http://xml.resource.org/profiles/TLS 1102 in the BEEP "profile" element during channel creation. 1104 During channel creation, the corresponding "profile" element in the 1105 BEEP "start" element may contain a "ready" element. If channel 1106 creation is successful, then before sending the corresponding reply, 1107 the BEEP peer processes the "ready" element and includes the 1108 resulting response in the reply, e.g., 1110 C: MSG 0 1 . 52 170 1111 C: Content-Type: application/beep+xml 1112 C: 1113 C: 1114 C: 1115 C: ]]> 1116 C: 1117 C: 1118 C: END 1119 S: RPY 0 1 . 122 133 1120 S: Content-Type: application/beep+xml 1121 S: 1122 S: 1123 S: ]]> 1124 S: 1125 S: END 1127 Note that it is possible for the channel to be created, but for the 1128 encapsulated operation to fail, e.g., 1130 C: MSG 0 1 . 52 185 1131 C: Content-Type: application/beep+xml 1132 C: 1133 C: 1134 C: 1135 C: ]]> 1136 C: 1137 C: 1138 C: END 1139 S: RPY 0 1 . 122 205 1140 S: Content-Type: application/beep+xml 1141 S: 1142 S: 1143 S: version attribute 1144 S: poorly formed in <ready> element]]> 1145 S: 1146 S: END 1148 In this case, a positive reply is sent (as channel creation 1149 succeeded), but the encapsulated response contains an indication as 1150 to why the operation failed. 1152 3.1.2 Message Syntax 1154 Section 7.2 defines the messages that are used in the TLS transport 1155 security profile. 1157 3.1.3 Message Semantics 1159 3.1.3.1 The Ready Message 1161 The "ready" element has an optional "version" attribute and no 1162 content: 1164 o the "version" element defines the earliest version of TLS 1165 acceptable for use. 1167 When a BEEP peer sends the "ready" element, it must not send any 1168 further traffic on the underlying transport service until a 1169 corresponding reply ("proceed" or "error") is received; similarly, 1170 the receiving BEEP peer must wait until any pending replies have 1171 been generated and sent before it processes a "ready" element. 1173 3.1.3.2 The Proceed Message 1175 The "proceed" element has no attributes and no content. It is sent 1176 as a reply to the "ready" element. 1178 When a BEEP peer receives the "ready" element, it must not send any 1179 further traffic on the underlying transport service until it 1180 generates a corresponding reply. If the BEEP peer decides to allow 1181 transport security negotation, it implicitly closes all channels 1182 (including channel zero), and sends the "proceed" element, and 1183 awaits the underlying negotiation process for transport security. 1185 When a BEEP peer receives a "proceed" element in reply to its 1186 "ready" message, it implicitly closes all channels (including 1187 channel zero), and immediately begins the underlying negotiation 1188 process for transport security. 1190 4. User Authentication 1192 When a BEEP session is established, anonymous access, without trace 1193 information, is provided. Accordingly, user authentication in BEEP 1194 is achieved using an initial tuning profile. 1196 This document defines a family of profiles based on SASL mechanisms: 1198 o each mechanism in the IANA SASL registry[15] has an associated 1199 profile. 1201 Other profiles may be defined and deployed on a bilateral basis. 1203 Whenever a successful authentication occurs, on any channel, the 1204 authenticated identity is updated for all existing and future 1205 channels on the BEEP session; further, no additional attempts at 1206 authentication are allowed. 1208 Note that regardless of transport security and user authentication, 1209 authorization is an internal matter for each BEEP peer. As such, 1210 each peer may choose to restrict the operations it allows based on 1211 the authentication credentials provided (i.e., unauthorized 1212 operations might be rejected with error code 530). 1214 4.1 The SASL Family of Profiles 1216 Section 6.3 contains the registration for this profile. 1218 Note that SASL may provide both user authentication and transport 1219 security. Once transport security is successfully negotiated for a 1220 BEEP session, then a SASL security layer must not be negotiated; 1221 similarly, once any SASL negotiation is successful, a transport 1222 security profile must not begin its underlying negotiation process. 1224 Section 4 of the SASL specification[4] requires the following 1225 information be supplied by a protocol definition: 1227 service name: "beep" 1229 initiation sequence: Creating a channel using a BEEP profile 1230 corresponding to a SASL mechanism starts the exchange. An 1231 optional parameter corresponding to the "initial response" sent 1232 by the client is carried within a "blob" element during channel 1233 creation. 1235 exchange sequence: "Challenges" and "responses" are carried in 1236 exchanges of the "blob" element. The "status" attribute of the 1237 "blob" element is used both by a server indicating a successful 1238 completion of the exchange, and a client aborting the exchange, 1239 The server indicates failure of the exchange by sending an 1240 "error" element. 1242 security layer negotiation: When a security layer starts 1243 negotiation, all channels (including channel zero) are closed on 1244 the BEEP session. Accordingly, upon completion of the negotiation 1245 process, regardless of its outcome, a new greeting is issued by 1246 both BEEP peers. 1248 If a security layer is successfully negotiated, it takes effect 1249 immediately following the message that concludes the server's 1250 successful completion reply. 1252 use of the authorization identity: This is made available to all 1253 channels for the duration of the BEEP session. 1255 4.1.1 Profile Identification and Initialization 1257 Each SASL mechanism registered with the IANA is identified as: 1259 http://xml.resource.org/profiles/sasl/MECHANISM 1261 where "MECHANISM" is the token assigned to that mechanism by the 1262 IANA. 1264 Note that during channel creation, a BEEP peer may provide multiple 1265 profiles to the remote peer, e.g., 1267 C: MSG 0 1 . 52 209 1268 C: Content-Type: application/beep+xml 1269 C: 1270 C: 1271 C: 1273 C: 1274 C: 1275 C: END 1276 S: RPY 0 1 . 264 99 1277 S: Content-Type: application/beep+xml 1278 S: 1279 S: 1280 S: END 1282 During channel creation, the corresponding "profile" element in the 1283 BEEP "start" element may contain a "blob" element. Note that it is 1284 possible for the channel to be created, but for the encapsulated 1285 operation to fail, e.g., 1287 C: MSG 0 1 . 52 195 1288 C: Content-Type: application/beep+xml 1289 C: 1290 C: 1291 C: 1292 C: AGJsb2NrbWFzdGVy]]> 1293 C: 1294 C: 1295 C: END 1296 S: RPY 0 1 . 264 190 1297 S: Content-Type: application/beep+xml 1298 S: 1299 S: 1300 S: authentication mechanism is 1301 S: too weak]]> 1302 S: 1303 S: END 1305 In this case, a positive reply is sent (as channel creation 1306 succeeded), but the encapsulated response contains an indication as 1307 to why the operation failed. 1309 Otherwise, the server sends a challenge (or signifies success), e.g., 1311 C: MSG 0 1 . 52 195 1312 C: Content-Type: application/beep+xml 1313 C: 1314 C: 1315 C: 1316 C: AGJsb2NrbWFzdGVy]]> 1317 C: 1318 C: 1319 C: END 1320 S: RPY 0 1 . 264 183 1321 S: Content-Type: application/beep+xml 1322 S: 1323 S: 1324 S: b3RwLXNoYTEgOTk5NyBwaXh5bWlzYXM4NTgwNSBleHQ= 1325 ]]> 1326 S: 1327 S: END 1329 Note that this example implies that the "blob" element in the 1330 server's reply appears on two lines -- this is an artifact of the 1331 presentation; in fact, only one line is used. 1333 If a challenge is received, then the client responds and awaits 1334 another reply, e.g., 1336 C: MSG 1 0 . 0 97 1337 C: Content-Type: application/beep+xml 1338 C: 1339 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n 1340 C: END 1341 S: RPY 1 0 . 0 66 1342 S: Content-Type: application/beep+xml 1343 S: 1344 S: 1345 S: END 1347 Of course, the client could abort the authentication process by 1348 sending "" instead. 1350 Alternatively, the server might reject the response with an error: 1351 e.g., 1353 C: MSG 1 0 . 0 97 1354 C: Content-Type: application/beep+xml 1355 C: 1356 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n 1357 C: END 1358 S: ERR 1 1 . 0 60 1359 S: Content-Type: application/beep+xml 1360 S: 1361 S: 1362 S: END 1364 Finally, depending on the SASL mechanism, an initialization element 1365 may be exchanged unidirectionally during channel creation, e.g., 1367 C: MSG 0 1 . 52 145 1368 C: Content-Type: application/beep+xml 1369 C: 1370 C: 1371 C: 1373 C: 1374 C: END 1375 S: RPY 0 1 . 264 197 1376 S: Content-Type: application/beep+xml 1377 S: 1378 S: 1379 S: PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1 1380 jaS5uZXQ+]]> 1381 S: 1382 S: END 1384 Note that this example implies that the "blob" element in the 1385 server's reply appears on two lines -- this is an artifact of the 1386 presentation; in fact, only one line is used. 1388 4.1.2 Message Syntax 1390 Section 7.3 defines the messages that are used for each profile in 1391 the SASL family. 1393 Note that because many SASL mechanisms exchange binary data, the 1394 content of the "blob" element is always a base64-encoded string. 1396 4.1.3 Message Semantics 1398 The "blob" element has an optional "status" attribute, and arbitrary 1399 octets as its content: 1401 o the "status" attribute, if present, takes one of three values: 1403 abort: used by a client to indicate that it is aborting the 1404 authentication process; 1406 complete: used by a server to indicate that the exchange is 1407 complete and successful; or, 1409 continue: used by either a client or server, otherwise. 1411 Finally, note that SASL's EXTERNAL mechanism works with an "external 1412 authentication" service, which is provided by one of: 1414 o a transport security profile, capable of providing authentication 1415 information (e.g., Section 3.1), being active on the connection; 1417 o a network service, capable of providing strong authentication 1418 (e.g., IPSec[12]), underlying the connection; or, 1420 o a locally-defined security service. 1422 For authentication to succeed, two conditions must hold: 1424 o an external authentication service must be active; and, 1426 o if present, the authentication identity must be consistent with 1427 the credentials provided by the external authentication service 1428 (if the authentication identity is empty, then an authorization 1429 identity is automatically derived from the credentials provided 1430 by the external authentication service). 1432 5. Registration Templates 1434 5.1 Profile Registration Template 1436 When a profile is registered, the following information is supplied: 1438 Profile Identification: specify a URI[10] that authoritatively 1439 identifies this profile. 1441 Message Exchanged during Channel Creation: specify the datatypes 1442 that may be exchanged during channel creation. 1444 Messages starting one-to-one exchanges: specify the datatypes that 1445 may be present when an exchange starts. 1447 Messages in positive replies: specify the datatypes that may be 1448 present in a positive reply. 1450 Messages in negative replies: specify the datatypes that may be 1451 present in a negative reply. 1453 Messages in one-to-many exchanges: specify the datatypes that may be 1454 present in a one-to-many exchange. 1456 Message Syntax: specify the syntax of the datatypes exchanged by the 1457 profile. 1459 Message Semantics: specify the semantics of the datatypes exchanged 1460 by the profile. 1462 Contact Information: specify the postal and electronic contact 1463 information for the author of the profile. 1465 5.2 Feature Registration Template 1467 When a feature for the channel management profile is registered, the 1468 following information is supplied: 1470 Feature Identification: specify a string that identifies this 1471 feature. Unless the feature is registered with the IANA, the 1472 feature's identification must start with "x-". 1474 Feature Semantics: specify the semantics of the feature. 1476 Contact Information: specify the postal and electronic contact 1477 information for the author of the feature. 1479 6. Initial Registrations 1481 6.1 Registration: BEEP Channel Management 1483 Profile Identification: not applicable 1485 Messages exchanged during Channel Creation: not applicable 1487 Messages starting one-to-one exchanges: "start" or "close" 1489 Messages in positive replies: "greeting", "profile", or "ok" 1491 Messages in negative replies: "error" 1493 Messages in one-to-many exchanges: none 1495 Message Syntax: c.f., Section 7.1 1497 Message Semantics: c.f., Section 2.3.1 1499 Contact Information: c.f., the "Author's Address" section of this 1500 memo 1502 6.2 Registration: TLS Transport Security Profile 1504 Profile Identification: http://xml.resource.org/profiles/TLS 1506 Messages exchanged during Channel Creation: "ready" 1508 Messages starting one-to-one exchanges: "ready" 1510 Messages in positive replies: "proceed" 1512 Messages in negative replies: "error" 1514 Messages in one-to-many exchanges: none 1516 Message Syntax: c.f., Section 7.2 1518 Message Semantics: c.f., Section 3.1.3 1520 Contact Information: c.f., the "Author's Address" section of this 1521 memo 1523 6.3 Registration: SASL Family of Profiles 1525 Profile Identification: 1526 http://xml.resource.org/profiles/sasl/MECHANISM, where 1527 "MECHANISM" is a token registered with the IANA[16] 1529 Messages exchanged during Channel Creation: "blob" 1531 Messages starting one-to-one exchanges: "blob" 1533 Messages in positive replies: "blob" 1535 Messages in negative replies: "error" 1537 Messages in one-to-many exchanges: none 1539 Message Syntax: c.f., Section 7.3 1541 Message Semantics: c.f., Section 4.1.3 1543 Contact Information: c.f., the "Author's Address" section of this 1544 memo 1546 6.4 Registration: application/beep+xml 1548 MIME media type name: application 1550 MIME subtype name: beep+xml 1552 Required parameters: none 1554 Optional parameters: charset (defaults to "UTF-8"[13]) 1556 Encoding considerations: This media type may contain binary content; 1557 accordingly, when used over a transport that does not permit 1558 binary transfer, an appropriate encoding must be applied 1560 Security considerations: none, per se; however, any BEEP profile 1561 which uses this media type must describe its relevant security 1562 considerations 1564 Interoperability considerations: n/a 1566 Published specification: This media type is a proper subset of the 1567 the XML 1.0 specification[2]. Two restrictions are made. 1569 First, no entity references other than the five predefined 1570 general entities references ("&", "<", ">", "'", 1571 and """) and numeric entity references may be present. 1573 Second, neither the "XML" declaration (e.g., ) nor the "DOCTYPE" declaration (e.g., ) may be 1575 present. (Accordingly, if another character set other than UTF-8 1576 is desired, then the "charset" parameter must be present.) 1578 All other XML 1.0 instructions (e.g., CDATA blocks, processing 1579 instructions, and so on) are allowed. 1581 Applications which use this media type: any BEEP profile wishing to 1582 make use of this XML 1.0 subset 1584 Additional Information: none 1586 Contact for further information: c.f., the "Author's Address" 1587 section of this memo 1589 Intended usage: limited use 1591 Author/Change controller: the IESG 1593 7. DTDs 1595 7.1 BEEP Channel Management DTD 1597 1607 1631 1632 1633 1634 1635 1636 1637 1649 1650 1654 1655 1659 1660 1661 1665 1666 1671 1673 1674 1678 7.2 TLS Transport Security Profile DTD 1680 1690 1698 1699 1702 1704 7.3 SASL Family of Profiles DTD 1706 1716 1724 1725 1731 8. Reply Codes 1733 code meaning 1734 ==== ======= 1735 200 success 1737 421 service not available 1739 450 requested action not taken 1740 (e.g., lock already in use) 1742 451 requested action aborted 1743 (e.g., local error in processing) 1745 454 temporary authentication failure 1747 500 general syntax error 1748 (e.g., poorly-formed XML) 1750 501 syntax error in parameters 1751 (e.g., non-valid XML) 1753 504 parameter not implemented 1755 530 authentication required 1757 534 authentication mechanism insufficient 1758 (e.g., too weak, sequence exhausted, etc.) 1760 535 authentication failure 1762 537 action not authorized for user 1764 538 authentication mechanism requires encryption 1766 550 requested action not taken 1767 (e.g., no requested profiles are acceptable) 1769 553 parameter invalid 1771 554 transaction failed 1772 (e.g., policy violation) 1774 9. Security Considerations 1776 The BEEP framing mechanism, per se, provides no protection against 1777 attack; however, judicious use of initial tuning profiles provides 1778 varying degrees of assurance: 1780 1. If one of the profiles from the SASL family is used, refer to 1781 [4]'s Section 9 for a discussion of security considerations. 1783 2. If the TLS transport security profile is used (or if a SASL 1784 security layer is negotiated), then: 1786 1. A man-in-the-middle may remove the security-related profiles 1787 from the BEEP greeting or generate a negative reply to the 1788 "ready" element of the TLS transport security profile. A 1789 BEEP peer may be configurable to refuse to proceed without 1790 an acceptable level of privacy. 1792 2. A man-in-the-middle may cause a down-negotiation to the 1793 weakest cipher suite available. A BEEP peer should be 1794 configurable to refuse weak cipher suites. 1796 3. A man-in-the-middle may modify any protocol exchanges prior 1797 to a successful negotiation. Upon completing the 1798 negotiation, a BEEP peer must discard previously cached 1799 information about the BEEP session. 1801 As different TLS ciphersuites provide varying levels of 1802 security, administrators should carefully choose which 1803 ciphersuites are provisioned. 1805 As BEEP is peer-to-peer in nature, before performing any task 1806 associated with a message, each channel should apply the appropriate 1807 access control based on the authenticated identity and privacy level 1808 associated with the BEEP session. 1810 References 1812 [1] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 1813 Extensions (MIME) Part One: Format of Internet Message 1814 Bodies", RFC 2045, November 1996. 1816 [2] World Wide Web Consortium, "Extensible Markup Language (XML) 1817 1.0", W3C XML, February 1998, 1818 . 1820 [3] Dierks, T., Allen, C., Treese, W., Karlton, P. L., Freier, A. 1821 O. and P. C. Kocher, "The TLS Protocol Version 1.0", RFC 2246, 1822 January 1999. 1824 [4] Myers, J.G., "Simple Authentication and Security Layer 1825 (SASL)", RFC 2222, October 1997. 1827 [5] Rose, M.T., "Mapping the BEEP Framework onto TCP", 1828 draft-ietf-beep-tcpmapping-05 (work in progress), December 1829 2000. 1831 [6] Postel, J., "Transmission Control Protocol", RFC 793, STD 7, 1832 Sep 1981. 1834 [7] Crocker, D. H. and P. Overell, "Augmented BNF for Syntax 1835 Specifications: ABNF", RFC 2234, November 1997. 1837 [8] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 1838 August 1996. 1840 [9] Alvestrand, H., "Tags for the Identification of Languages", 1841 RFC 1766, March 1995. 1843 [10] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform 1844 Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1845 1998. 1847 [11] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444, 1848 October 1998. 1850 [12] Kent, S. and R. Atkinson, "Security Architecture for the 1851 Internet Protocol", RFC 2401, November 1998. 1853 [13] Yergeau, F., "UTF-8, a transformation format of ISO 10646", 1854 RFC 2279, January 1998. 1856 [14] Linn, J., "Generic Security Service Application Program 1857 Interface, Version 2", RFC 2078, January 1997. 1859 [15] 1861 [16] 1863 Author's Address 1865 Marshall T. Rose 1866 Invisible Worlds, Inc. 1867 1179 North McDowell Boulevard 1868 Petaluma, CA 94954-6559 1869 US 1871 Phone: +1 707 789 3700 1872 EMail: mrose@invisible.net 1873 URI: http://invisible.net/ 1875 Appendix A. Acknowledgements 1877 The author gratefully acknowledges the contributions of: David 1878 Clark, Dave Crocker, Steve Deering, Wesley Michael Eddy, Huston 1879 Franklin, Marco Gazzetta, Danny Goodman, Steve Harris, Robert 1880 Herriot, Ken Hirsch, Greg Hudson, Ben Laurie, Carl Malamud, Michael 1881 Mealling, Keith McCloghrie, Paul Mockapetris, RL 'Bob' Morgan, Frank 1882 Morton, Darren New, Chris Newman, Joe Touch, Paul Vixie, Gabe 1883 Wachob, Daniel Woods, and, James Woodyatt. In particular, Dave 1884 Crocker provided helpful suggestions on the nature of segmentation 1885 in the framing mechanism. 1887 Appendix B. IANA Considerations 1889 The IANA registers "beep" as a GSSAPI[14] service name, as specified 1890 in Section 4.1. 1892 The IANA maintains a list of: 1894 o standards-track BEEP profiles, c.f., Section 5.1; and, 1896 o standards-track features for the channel management profile, 1897 c.f., Section 5.2. 1899 For each list, the IESG is responsible for assigning a designated 1900 expert to review the specification prior to the IANA making the 1901 assignment. As a courtesy to developers of non-standards track BEEP 1902 profiles and channel management features, the mailing list 1903 bxxpwg@invisible.net may be used to solicit commentary. 1905 The IANA makes the registrations specified in Section 6.2 and 1906 Section 6.3. It is recommended that the IANA register these profiles 1907 using the IANA as a URI-prefix, and populate those URIs with the 1908 respective profile registrations. 1910 Full Copyright Statement 1912 Copyright (C) The Internet Society (2000). All Rights Reserved. 1914 This document and translations of it may be copied and furnished to 1915 others, and derivative works that comment on or otherwise explain it 1916 or assist in its implementation may be prepared, copied, published 1917 and distributed, in whole or in part, without restriction of any 1918 kind, provided that the above copyright notice and this paragraph 1919 are included on all such copies and derivative works. However, this 1920 document itself may not be modified in any way, such as by removing 1921 the copyright notice or references to the Internet Society or other 1922 Internet organizations, except as needed for the purpose of 1923 developing Internet standards in which case the procedures for 1924 copyrights defined in the Internet Standards process must be 1925 followed, or as required to translate it into languages other than 1926 English. 1928 The limited permissions granted above are perpetual and will not be 1929 revoked by the Internet Society or its successors or assigns. 1931 This document and the information contained herein is provided on an 1932 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1933 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1934 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1935 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1936 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1938 Acknowledgement 1940 Funding for the RFC editor function is currently provided by the 1941 Internet Society.