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