idnits 2.17.1
draft-ietf-beep-framework-04.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 1481: '...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 1604 has weird spacing: '...reeting err...'
== Line 1695 has weird spacing: '... code mea...'
-- The document seems to lack a disclaimer for pre-RFC5378 work, but may
have content which was first submitted before 10 November 2008. If you
have contacted all the original authors and they are all willing to grant
the BCP78 rights to the IETF Trust, then this is fine, and you can ignore
this comment. If not, you may need to add the pre-RFC5378 disclaimer.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (October 10, 2000) is 8596 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 1578
-- Looks like a reference, but probably isn't: 'RFC-1766' on line 1587
-- Looks like a reference, but probably isn't: '1-5' on line 1590
-- Looks like a reference, but probably isn't: '1-9' on line 1590
== Unused Reference: '10' is defined on line 1803, 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-04
** Obsolete normative reference: RFC 793 (ref. '6') (Obsoleted by RFC 9293)
** Obsolete normative reference: RFC 2234 (ref. '7') (Obsoleted by RFC 4234)
** Obsolete normative reference: RFC 1766 (ref. '8') (Obsoleted by RFC
3066, RFC 3282)
** Obsolete normative reference: RFC 2396 (ref. '9') (Obsoleted by RFC 3986)
** Obsolete normative reference: RFC 2401 (ref. '11') (Obsoleted by RFC
4301)
** Obsolete normative reference: RFC 2078 (ref. '12') (Obsoleted by RFC
2743)
-- Possible downref: Non-RFC (?) normative reference: ref. '13'
-- Possible downref: Non-RFC (?) normative reference: ref. '14'
Summary: 11 errors (**), 0 flaws (~~), 7 warnings (==), 9 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M.T. Rose
3 Internet-Draft Invisible Worlds, Inc.
4 Expires: April 10, 2001 October 10, 2000
6 The Blocks Extensible Exchange Protocol Framework
7 draft-ietf-beep-framework-04
9 Status of this Memo
11 This document is an Internet-Draft and is in full conformance with
12 all provisions of Section 10 of RFC2026.
14 Internet-Drafts are working documents of the Internet Engineering
15 Task Force (IETF), its areas, and its working groups. Note that
16 other groups may also distribute working documents as
17 Internet-Drafts.
19 Internet-Drafts are draft documents valid for a maximum of six
20 months and may be updated, replaced, or obsoleted by other documents
21 at any time. It is inappropriate to use Internet-Drafts as reference
22 material or to cite them other than as "work in progress."
24 The list of current Internet-Drafts can be accessed at
25 http://www.ietf.org/ietf/1id-abstracts.txt.
27 The list of Internet-Draft Shadow Directories can be accessed at
28 http://www.ietf.org/shadow.html.
30 This Internet-Draft will expire on April 10, 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 . . . . . . . . . . . . . . . . . . . . 18
62 2.3.1.3 The Close Message . . . . . . . . . . . . . . . . . . . . 21
63 2.3.1.4 The OK Message . . . . . . . . . . . . . . . . . . . . . . 23
64 2.3.1.5 The Error Message . . . . . . . . . . . . . . . . . . . . 23
65 2.4 Session Establishment and Release . . . . . . . . . . . . 25
66 2.5 Transport Mappings . . . . . . . . . . . . . . . . . . . . 27
67 2.5.1 Session Management . . . . . . . . . . . . . . . . . . . . 27
68 2.5.2 Message Exchange . . . . . . . . . . . . . . . . . . . . . 27
69 2.6 Parallelism . . . . . . . . . . . . . . . . . . . . . . . 28
70 2.6.1 Within a Single Channel . . . . . . . . . . . . . . . . . 28
71 2.6.2 Between Different Channels . . . . . . . . . . . . . . . . 28
72 2.6.3 Pre-emptive Replies . . . . . . . . . . . . . . . . . . . 28
73 2.6.4 Interference . . . . . . . . . . . . . . . . . . . . . . . 28
74 2.7 Peer-to-Peer Behavior . . . . . . . . . . . . . . . . . . 29
75 3. Transport Security . . . . . . . . . . . . . . . . . . . . 30
76 3.1 The TLS Transport Security Profile . . . . . . . . . . . . 33
77 3.1.1 Profile Identification and Initialization . . . . . . . . 33
78 3.1.2 Message Syntax . . . . . . . . . . . . . . . . . . . . . . 34
79 3.1.3 Message Semantics . . . . . . . . . . . . . . . . . . . . 35
80 3.1.3.1 The Ready Message . . . . . . . . . . . . . . . . . . . . 35
81 3.1.3.2 The Proceed Message . . . . . . . . . . . . . . . . . . . 35
82 4. User Authentication . . . . . . . . . . . . . . . . . . . 36
83 4.1 The SASL Family of Profiles . . . . . . . . . . . . . . . 37
84 4.1.1 Profile Identification and Initialization . . . . . . . . 38
85 4.1.2 Message Syntax . . . . . . . . . . . . . . . . . . . . . . 41
86 4.1.3 Message Semantics . . . . . . . . . . . . . . . . . . . . 42
87 5. Registration Templates . . . . . . . . . . . . . . . . . . 43
88 5.1 Profile Registration Template . . . . . . . . . . . . . . 43
89 5.2 Feature Registration Template . . . . . . . . . . . . . . 43
90 6. Initial Registrations . . . . . . . . . . . . . . . . . . 44
91 6.1 Registration: BEEP Channel Management . . . . . . . . . . 44
92 6.2 Registration: TLS Transport Security Profile . . . . . . . 44
93 6.3 Registration: SASL Family of Profiles . . . . . . . . . . 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 119 octets spread over 5 lines (each line is
220 terminated with a CRLF pair):
222 C: MSG 0 1 . 40 120
223 C: Content-Type: text/xml
224 C:
225 C:
226 C:
227 C:
228 C: END
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 for which a reply has not been completely received.
277 The continuation indicator ("more", one of: decimal code 42, "*", or
278 decimal code 46, ".") specifies whether this is the final frame of
279 the message:
281 intermediate ("*"): at least one other frame follows for the
282 message; or,
284 complete ("."): this frame completes the message.
286 The sequence number ("seqno") must be a non-negative integer (in the
287 range 0..4294967295) and specifies the sequence number of the first
288 octet in the payload, for the associated channel.
290 The payload size ("size") must be a non-negative integer (in the
291 range 0..2147483647) and specifies the exact number of octets in the
292 payload. (This does not include either the header or trailer.)
294 Note that a frame may have an empty payload, e.g.,
296 S: RPY 0 1 * 287 20
297 S: ...
298 S: ...
299 S: END
300 S: RPY 0 1 . 307 0
301 S: END
303 The answer number ("ansno") must be a non-negative integer (in the
304 range 0..4294967295) and must have a different value than all other
305 answers in progress for the message being replied to.
307 There are two kinds of frames: data and mapping. each transport
308 mapping (c.f., Section 2.5) may define its own frames. For example,
309 [5] defines the SEQ frame. The remainder of this section discusses
310 data frames.
312 When a message is segmented and sent as several frames, those frames
313 must be sent sequentally, without any intervening frames from other
314 messages on the same channel. However, there are two exceptions:
315 first, no restriction is made with respect to the interleaving of
316 frames for other channels; and, second, in a one-to-many exchange,
317 multiple answers may be simultaneously in progress. Accordingly,
318 frames for "ANS" messages may be interleaved on the same channel --
319 the answer number is used for collation, e.g.,
321 S: ANS 1 0 * 0 20 0
322 S: ...
323 S: ...
324 S: END
325 S: ANS 1 0 * 20 20 1
326 S: ...
327 S: ...
328 S: END
329 S: ANS 1 0 . 40 10 0
330 S: ...
331 S: END
333 which shows two "ANS" messages interleaved on channel 1 as part of a
334 reply to message number 0. Note that the sequence number is advanced
335 for each frame sent on the channel, and is independent of the
336 messages sent in those frames.
338 There are several rules for identifying poorly-formed frames:
340 o if the header doesn't start with "MSG", "RPY", "ERR", "ANS", or
341 "NUL";
343 o if any of the parameters in the header cannot be determined or
344 are invalid (i.e., syntactically incorrect);
346 o if the value of the channel number doesn't refer to an existing
347 channel;
349 o if the header starts with "MSG", and the message number refers to
350 a "MSG" message that has been completely received but for which a
351 reply has not been completely sent;
353 o if the header doesn't start with "MSG", and refers to a message
354 number for which a reply has not been completely received;
356 o if the header doesn't start with "MSG", and refers to a message
357 number that has never been sent (except during session
358 establishment, c.f., Section 2.3.1.1);
360 o if the header starts with "MSG", "ERR", or "ANS", and refers to a
361 message number for which at least one other frame has been
362 received, and the three-character keyword starting this frame and
363 the immediately-previous received frame for this reply are not
364 identical;
366 o if the header starts with "NUL", and refers to a message number
367 for which at least one other frame has been received, and the
368 keyword of of the immediately-previous received frame for this
369 reply isn't "ANS";
371 o if the continuation indicator of the previous frame received on
372 the same channel was intermediate ("*"), and its message number
373 isn't identical to this frame's message number;
375 o if the value of the sequence number doesn't correspond to the
376 expected value for the associated channel (c.f., Section
377 2.2.1.2); or,
379 o if the header starts with "NUL", and the continuation indicator
380 is intermediate ("*") or the payload size is non-zero.
382 If a frame is poorly-formed, then the session is terminated without
383 generating a response, and it is recommended that a diagnostic entry
384 be logged.
386 2.2.1.2 Frame Payload
388 The frame payload consists of zero or more octets.
390 Every payload octet sent in each direction on a channel has an
391 associated sequence number. Numbering of payload octets within a
392 frame is such that the first payload octet is the lowest numbered,
393 and the following payload octets are numbered consecutively. (When a
394 channel is created, the sequence number associated with the first
395 payload octet of the first frame is 0.)
397 The actual sequence number space is finite, though very large,
398 ranging from 0..4294967295 (2**32 - 1). Since the space is finite,
399 all arithmetic dealing with sequence numbers is performed modulo
400 2**32. This unsigned arithmetic preserves the relationship of
401 sequence numbers as they cycle from 2**32 - 1 to 0 again.
403 When receiving a frame, the sum of its sequence number and payload
404 size, modulo 4294967296 (2**32), gives the expected sequence number
405 associated with the first payload octet of the next frame received.
406 Accordingly, when receiving a frame if the sequence number isn't the
407 expected value for this channel, then the BEEP peers have lost
408 synchronization, then the session is terminated without generating a
409 response, and it is recommended that a diagnostic entry be logged.
411 2.2.1.3 Frame Trailer
413 The frame trailer consists of "END" followed by a CRLF pair.
415 When receiving a frame, if the characters immediately following the
416 payload don't correspond to a trailer, then the session is
417 terminated without generating a response, and it is recommended that
418 a diagnostic entry be logged.
420 2.2.2 Frame Semantics
422 The semantics of each message is channel-specific. Accordingly, the
423 profile associated with a channel must define:
425 o the initialization messages, if any, exchanged during channel
426 creation;
428 o the messages that may be exchanged in the payload of the channel;
429 and,
431 o the semantics of these messages.
433 A profile registration template (Section 5.1) organizes this
434 information.
436 2.2.2.1 Poorly-formed Messages
438 When defining the behavior of the profile, the template must specify
439 how poorly-formed "MSG" messages are replied to. For example, the
440 channel management profile sends a negative reply containing an
441 error message (c.f., Section 2.3.1.5).
443 If a poorly-formed reply is received on channel zero, the session is
444 terminated without generating a response, and it is recommended that
445 a diagnostic entry be logged.
447 If a poorly-formed reply is received on another channel, then the
448 channel must be closed using the procedure in Section 2.3.1.3.
450 2.2.2.2 XML-based Profiles
452 If a profile uses XML[2] to structure its messages, then only XML's
453 baseline facilities (as described in the XML 1.0 specification[2])
454 are allowed. Additional XML facilities (e.g., namespaces) are made
455 available only by being explicitly permitted in a given profile's
456 specification.
458 In particular this limitation allows use of only the five predefined
459 general entities references ("&", "<", ">", "'", and
460 """) and numeric entity references in the messages exchanged.
462 Further, because the profile registration template defines the
463 messages exchanged over a channel, the XML documents exchanged in
464 each message needn't have either a "XML" declaration (e.g., ) or a "DOCTYPE" declaration (e.g., ).
466 All other XML 1.0 instructions (e.g., CDATA blocks, processing
467 instructions, and so on) are allowed.
469 Finally, because the "XML" declaration isn't present, the default
470 character set for XML-based profiles is UTF-8. If another character
471 set is desired, the "Content-Type" entity-header must indicate this.
473 2.3 Channel Management
475 When a BEEP session starts, only channel number zero is defined,
476 which is used for channel management. Section 6.1 contains the
477 profile registration for BEEP channel management.
479 Channel management allows each BEEP peer to advertise the profiles
480 that it supports (c.f., Section 2.3.1.1), bind an instance of one of
481 those profiles to a channel (c.f., Section 2.3.1.2), and then later
482 close any channels or release the BEEP session (c.f., Section
483 2.3.1.3).
485 A BEEP peer should support at least 257 concurrent channels.
487 2.3.1 Message Semantics
489 2.3.1.1 The Greeting Message
491 When a BEEP session is established, each BEEP peer signifies its
492 availability by immediately sending a positive reply with a message
493 number of zero that contains a "greeting" element, e.g.,
495 L:
496 I:
497 L: RPY 0 0 . 0 110
498 L: Content-Type: text/xml
499 L:
500 L:
501 L:
502 L:
503 L: END
504 I: RPY 0 0 . 0 40
505 I: Content-Type: text/xml
506 I:
507 I:
508 I: END
510 Note that this example implies that the BEEP peer in the initiating
511 role waits until the BEEP peer in the listening role sends its
512 greeting -- this is an artifact of the presentation; in fact, both
513 BEEP peers send their replies independently.
515 The "greeting" element has two optional attributes ("features" and
516 "localize") and zero or more "profile" elements, one for each
517 profile supported by the BEEP peer acting in a server role:
519 o the "features" attribute, if present, contains one or more
520 feature tokens, each indicating an optional feature of the
521 channel management profile supported by the BEEP peer;
523 o the "localize" attribute, if present, contains one or more
524 language tokens (defined in [8]), each identifying a desirable
525 language tag to be used by the remote BEEP peer when generating
526 textual diagnostics for the "close" and "error" elements (the
527 tokens are ordered from most to least desirable); and,
529 o each "profile" element contained within the "greeting" element
530 identifies a profile, and unlike the "profile" elements that
531 occur within the "start" element, the content of each "profile"
532 element may not contain an optional initialization message.
534 Section 5.2 defines a registration template for optional features.
536 2.3.1.2 The Start Message
538 When a BEEP peer wants to create a channel, it sends a "start"
539 element on channel zero, e.g.,
541 C: MSG 0 1 . 40 120
542 C: Content-Type: text/xml
543 C:
544 C:
545 C:
546 C:
547 C: END
549 The "start" element has a "number" attribute, an optional
550 "serverName" attribute, and one or more "profile" elements:
552 o the "number" attribute indicates the channel number (in the range
553 1..2147483647) used to identify the channel in future messages;
555 o the "serverName" attribute, an arbitrary string, indicates the
556 desired server name for this BEEP session; and,
558 o each "profile" element contained with the "start" element has a
559 "uri" attribute, an optional "encoding" attribute, and arbitrary
560 character data as content:
562 * the "uri" attribute authoritatively identifies the profile;
564 * the "encoding" attribute, if present, specifies whether the
565 content of the "profile" element is represented as a
566 base64-encoded string; and,
568 * the content of the "profile" element, if present, must be no
569 longer than 4K octets in length and specifies an
570 initialization message given to the channel as soon as it is
571 created.
573 To avoid conflict in assigning channel numbers when requesting the
574 creation of a channel, BEEP peers acting in the initiating role use
575 only positive integers that are odd-numbered; similarly, BEEP peers
576 acting in the listening role use only positive integers that are
577 even-numbered.
579 The "serverName" attribute for the first successful "start" element
580 received by a BEEP peer is meaningful for the duration of the BEEP
581 session. If present, the BEEP peer decides whether to operate as the
582 indicated "serverName"; if not, an "error" element is sent in a
583 negative reply.
585 When a BEEP peer receives a "start" element on channel zero, it
586 examines each of the proposed profiles, and decides whether to use
587 one of them to create the channel. If so, the appropriate "profile"
588 element is sent in a positive reply; otherwise, an "error" element
589 is sent in a negative reply.
591 When creating the channel, the value of the "serverName" attribute
592 from the first successful "start" element is consulted to provide
593 configuration information, e.g., the desired server-side certificate
594 when starting the TLS transport security profile (Section 3.1).
596 For example, a successful channel creation might look like this:
598 C: MSG 0 1 . 40 197
599 C: Content-Type: text/xml
600 C:
601 C:
602 C:
603 C:
605 C:
606 C: END
607 S: RPY 0 1 . 252 87
608 S: Content-Type: text/xml
609 S:
610 S:
611 S: END
613 Similarly, an unsuccessful channel creation might look like this:
615 C: MSG 0 1 . 40 120
616 C: Content-Type: text/xml
617 C:
618 C:
619 C:
620 C:
621 C: END
622 S: ERR 0 1 . 252 115
623 S: Content-Type: text/xml
624 S:
625 S: number attribute
626 S: in <start> element must be odd-valued
627 S: END
629 Finally, here's an example in which an initialization element is
630 exchanged during channel creation:
632 C: MSG 0 1 . 40 158
633 C: Content-Type: text/xml
634 C:
635 C:
636 C:
637 C: ]]>
638 C:
639 C:
640 C: END
641 S: RPY 0 1 . 110 121
642 S: Content-Type: text/xml
643 S:
644 S:
645 S: ]]>
646 S:
647 S: END
649 2.3.1.3 The Close Message
651 When a BEEP peer wants to close a channel, it sends a "close"
652 element on channel zero, e.g.,
654 C: MSG 0 2 . 223 59
655 C: Content-Type: text/xml
656 C:
657 C:
658 C: END
660 The "close" element has a "number" attribute, a "code" attribute, an
661 optional "xml:lang" attribute, and an optional textual diagnostic as
662 its content:
664 o the "number" attribute indicates the channel number;
666 o the "code" attribute is a three-digit reply code meaningful to
667 programs (c.f., Section 8);
669 o the "xml:lang" attribute identifies the language that the
670 element's content is written in (the value is suggested, but not
671 mandated, by the "localize" attribute of the "greeting" element
672 sent by the remote BEEP peer); and,
674 o the textual diagnostic (which may be multiline) is meaningful to
675 implementers, perhaps administrators, and possibly even users,
676 but never programs.
678 Note that if the textual diagnostic is present, then the "xml:lang"
679 attribute is absent only if the language indicated as the remote
680 BEEP peer's first choice is used.
682 If the value of the "number" attribute is zero, then the BEEP peer
683 wants to release the BEEP session (c.f., Section 2.4) -- otherwise
684 the value of the "number" attribute refers to an existing channel.
686 When a BEEP peer receives a "close" element on channel zero, it
687 decides whether it is willing to close the channel. If so, an "ok"
688 element is sent in a positive reply; otherwise, an "error" element
689 is sent in a negative reply.
691 For example, a successful channel close might look like this:
693 C: MSG 0 2 . 223 59
694 C: Content-Type: text/xml
695 C:
696 C:
697 C: END
698 S: RPY 0 2 . 423 34
699 S: Content-Type: text/xml
700 S:
701 S:
702 S: END
704 Similarly, an unsuccessful channel close might look like this:
706 C: MSG 0 2 . 223 59
707 C: Content-Type: text/xml
708 C:
709 C:
710 C: END
711 S: ERR 0 2 . 423 67
712 S: Content-Type: text/xml
713 S:
714 S: still working
715 S: END
717 2.3.1.4 The OK Message
719 When a BEEP peer agrees to close a channel (or release the BEEP
720 session), it sends an "ok" element in a positive reply.
722 The "ok" element has no attributes and no content.
724 2.3.1.5 The Error Message
726 When a BEEP peer declines the creation of a channel, it sends an
727 "error" element in a negative reply, e.g.,
729 I: MSG 0 1 . 40 115
730 I: Content-Type: text/xml
731 I:
732 I:
733 I:
734 I:
735 I: END
736 L: ERR 0 1 . 252 93
737 L: Content-Type: text/xml
738 L:
739 L: all requested profiles are
740 L: unsupported
741 L: END
743 The "error" element has a "code" attribute, an optional "xml:lang"
744 attribute, and an optional textual diagnostic as its content:
746 o the "code" attribute is a three-digit reply code meaningful to
747 programs (c.f., Section 8);
749 o the "xml:lang" attribute identifies the language that the
750 element's content is written in (the value is suggested, but not
751 mandated, by the "localize" attribute of the "greeting" element
752 sent by the remote BEEP peer); and,
754 o the textual diagnostic (which may be multiline) is meaningful to
755 implementers, perhaps administrators, and possibly even users,
756 but never programs.
758 Note that if the textual diagnostic is present, then the "xml:lang"
759 attribute is absent only if the language indicated as the remote
760 BEEP peer's first choice is used.
762 In addition, a BEEP peer sends an "error" element whenever:
764 o it receives a "MSG" message containing a poorly-formed or
765 unexpected element;
767 o it receives a "MSG" message asking to close a channel (or release
768 the BEEP session) and it declines to do so; or
770 o a BEEP session is established, the BEEP peer is acting in the
771 listening role, and that BEEP peer is unavailable (in this case,
772 the BEEP acting in the listening role does not send a "greeting"
773 element).
775 In the final case, both BEEP peers terminate the session, and it is
776 recommended that a diagnostic entry be logged by both BEEP peers.
778 2.4 Session Establishment and Release
780 When a BEEP session is established, each BEEP peer signifies its
781 availability by immediately sending a positive reply with a message
782 number of zero on channel zero that contains a "greeting" element,
783 e.g.,
785 L:
786 I:
787 L: RPY 0 0 . 0 110
788 L: Content-Type: text/xml
789 L:
790 L:
791 L:
792 L:
793 L: END
794 I: RPY 0 0 . 0 40
795 I: Content-Type: text/xml
796 I:
797 I:
798 I: END
800 Alternatively, if the BEEP peer acting in the listening role is
801 unavailable, it sends a negative reply, e.g.,
803 L:
804 I:
805 L: ERR 0 0 . 0 48
806 L: Content-Type: text/xml
807 L:
808 L:
809 L: END
810 I: RPY 0 0 . 0 40
811 I: Content-Type: text/xml
812 I:
813 I:
814 I: END
815 I:
816 L:
817 L:
819 and the "greeting" element sent by the BEEP peer acting in the
820 initiating role is ignored. It is recommended that a diagnostic
821 entry be logged by both BEEP peers.
823 Note that both of these examples imply that the BEEP peer in the
824 initiating role waits until the BEEP peer in the listening role
825 sends its greeting -- this is an artifact of the presentation; in
826 fact, both BEEP peers send their replies independently.
828 When a BEEP peer wants to release the BEEP session, it sends a
829 "close" element with a zero-valued "number" attribute on channel
830 zero. The other BEEP peer indicates its willingness by sending an
831 "ok" element in a positive reply, e.g.,
833 C: MSG 0 1 . 40 48
834 C: Content-Type: text/xml
835 C:
836 C:
837 C: END
838 S: RPY 0 1 . 252 34
839 S: Content-Type: text/xml
840 S:
841 S:
842 S: END
843 I:
844 L:
845 L:
847 Alternatively, if the other BEEP doesn't want to release the BEEP
848 session, the exchange might look like this:
850 C: MSG 0 1 . 40 48
851 C: Content-Type: text/xml
852 C:
853 C:
854 C: END
855 S: ERR 0 1 . 252 67
856 S: Content-Type: text/xml
857 S:
858 S: still working
859 S: END
861 If session release is declined, the BEEP session should not be
862 terminated, if possible.
864 2.5 Transport Mappings
866 All transport interactions occur in the context of a session -- a
867 mapping onto a particular transport service. Accordingly, this memo
868 defines the requirements that must be satisified by any document
869 describing how a particular transport service realizes a BEEP
870 session.
872 2.5.1 Session Management
874 A BEEP session is connection-oriented. A mapping document must
875 define:
877 o how a BEEP session is established;
879 o how a BEEP peer is identified as acting in the listening role;
881 o how a BEEP peer is identified as acting in the initiating role;
883 o how a BEEP session is released; and,
885 o how a BEEP session is terminated.
887 2.5.2 Message Exchange
889 A BEEP session is message-oriented. A mapping document must define:
891 o how messages are reliably sent and received;
893 o how messages on the same channel are received in the same order
894 as they were sent; and,
896 o how messages on different channels are sent without ordering
897 constraint.
899 2.6 Parallelism
901 2.6.1 Within a Single Channel
903 A BEEP peer acting in the client role may send multiple "MSG"
904 messages on the same channel without waiting to receive the
905 corresponding replies.
907 A BEEP peer acting in the server role must process all "MSG"
908 messages for a given channel in the same order as they are received.
909 As a consequence, the BEEP peer must generate replies in the same
910 order as the corresponding "MSG" messages are received on a given
911 channel.
913 2.6.2 Between Different Channels
915 A BEEP peer acting in the client role may send multiple "MSG"
916 messages on different channels without waiting to receive the
917 corresponding replies.
919 A BEEP peer acting in the server role may process "MSG" messages
920 received on different channels in any order it chooses. As a
921 consequence, although the replies for a given channel appear to be
922 generated in the same order in which the corresponding "MSG"
923 messages are received, there is no ordering constraint for replies
924 on different channels.
926 2.6.3 Pre-emptive Replies
928 A BEEP peer acting in the server role may send a negative reply
929 before it receives the final "MSG" frame of a message. If it does
930 so, that BEEP peer is obliged to ignore any subsequent "MSG" frames
931 for that message, up to and including the final "MSG" frame.
933 If a BEEP peer acting in the client role receives a negative reply
934 before it sends the final "MSG" frame for a message, then it is
935 required to send a "MSG" frame with a continuation status of
936 complete (".") and having a zero-length payload.
938 2.6.4 Interference
940 If the processing of a particular message has sequencing impacts on
941 other messages (either intra-channel or inter-channel), then the
942 corresponding profile should define this behavior, e.g., a profile
943 whose messages alter the underlying transport mapping.
945 2.7 Peer-to-Peer Behavior
947 BEEP is peer-to-peer -- as such both peers must be prepared to
948 receive all messages defined in this memo. Accordingly, an
949 initiating BEEP peer capable of acting only in the client role must
950 behave gracefully if it receives a "MSG" message. Accordingly, all
951 profiles must provide an appropriate error message for replying to
952 unexpected "MSG" messages.
954 As a consequence of the peer-to-peer nature of BEEP, message numbers
955 are unidirectionally-significant. That is, the message numbers in
956 "MSG" messages sent by a BEEP peer acting in the initiating role are
957 unrelated to the message numbers in "MSG" messages sent by a BEEP
958 peer acting in the listening role.
960 For example, these two messages
962 I: MSG 0 1 . 40 120
963 I: Content-Type: text/xml
964 I:
965 I:
966 I:
967 I:
968 I: END
969 L: MSG 0 1 . 252 116
970 L: Content-Type: text/xml
971 L:
972 L:
973 L:
974 L:
975 L: END
977 refer to different messages sent on channel zero.
979 3. Transport Security
981 When a BEEP session is established, plaintext transfer, without
982 privacy, is provided. Accordingly, transport security in BEEP is
983 achieved using an initial tuning profile.
985 This document defines one profile:
987 o the TLS transport security profile, based on TLS version one[3].
989 Other profiles may be defined and deployed on a bilateral basis.
990 Note that because of their intimate relationship with the tranpsort
991 service, a given transport security profile tends to be relevant to
992 a single transort mapping (c.f., Section 2.5).
994 When a channel associated with transport security begins the
995 underlying negotiation process, all channels (including channel
996 zero) are closed on the BEEP session. Accordingly, upon completion
997 of the negotiation process, regardless of its outcome, a new
998 greeting is issued by both BEEP peers. (If the negotiation process
999 fails, then either BEEP peer may instead terminate the session, and
1000 it is recommended that a diagnostic entry be logged.)
1002 A BEEP peer may choose to issue different greetings based on whether
1003 privacy is in use, e.g.,
1005 L:
1006 I:
1007 L: RPY 0 0 . 0 110
1008 L: Content-Type: text/xml
1009 L:
1010 L:
1011 L:
1012 L:
1013 L: END
1014 I: RPY 0 0 . 0 40
1015 I: Content-Type: text/xml
1016 I:
1017 I:
1018 I: END
1019 I: MSG 0 1 . 40 158
1020 I: Content-Type: text/xml
1021 I:
1022 I:
1023 I:
1024 I: ]]>
1025 I:
1026 I:
1027 I: END
1028 L: RPY 0 1 . 110 121
1029 L: Content-Type: text/xml
1030 L:
1031 L:
1032 L: ]]>
1033 L:
1034 L: END
1036 ... successful transport security negotiation ...
1038 L: RPY 0 0 . 0 252
1039 L: Content-Type: text/xml
1040 L:
1041 L:
1042 L:
1044 L:
1045 L:
1046 L:
1047 L: END
1048 I: RPY 0 0 . 0 40
1049 I: Content-Type: text/xml
1050 I:
1051 I:
1052 I: END
1054 Of course, not all BEEP peers need be as single-minded:
1056 L:
1057 I:
1058 L: RPY 0 0 . 0 311
1059 L: Content-Type: text/xml
1060 L:
1061 L:
1062 L:
1064 L:
1065 L:
1066 L:
1067 L:
1068 L: END
1069 I: RPY 0 0 . 0 40
1070 I: Content-Type: text/xml
1071 I:
1072 I:
1073 I: END
1074 I: MSG 0 1 . 40 158
1075 I: Content-Type: text/xml
1076 I:
1078 I:
1079 I:
1080 I: ]]>
1081 I:
1082 I:
1083 I: END
1084 L: RPY 0 1 . 311 121
1085 L: Content-Type: text/xml
1086 L:
1087 L:
1088 L: ]]>
1089 L:
1090 L: END
1092 ... failed transport security negotiation ...
1094 L: RPY 0 0 . 0 311
1095 L: Content-Type: text/xml
1096 L:
1097 L:
1098 L:
1100 L:
1101 L:
1102 L:
1103 L:
1104 L: END
1105 I: RPY 0 0 . 0 40
1106 I: Content-Type: text/xml
1107 I:
1108 I:
1109 I: END
1111 3.1 The TLS Transport Security Profile
1113 Section 6.2 contains the registration for this profile.
1115 3.1.1 Profile Identification and Initialization
1117 The TLS transport security profile is identified as:
1119 http://xml.resource.org/profiles/TLS
1121 in the BEEP "profile" element during channel creation.
1123 During channel creation, the corresponding "profile" element in the
1124 BEEP "start" element may contain a "ready" element. If channel
1125 creation is successful, then before sending the corresponding reply,
1126 the BEEP peer processes the "ready" element and includes the
1127 resulting response in the reply, e.g.,
1129 C: MSG 0 1 . 40 158
1130 C: Content-Type: text/xml
1131 C:
1132 C:
1133 C:
1134 C: ]]>
1135 C:
1136 C:
1137 C: END
1138 S: RPY 0 1 . 110 121
1139 S: Content-Type: text/xml
1140 S:
1141 S:
1142 S: ]]>
1143 S:
1144 S: END
1146 Note that it is possible for the channel to be created, but for the
1147 encapsulated operation to fail, e.g.,
1149 C: MSG 0 1 . 40 173
1150 C: Content-Type: text/xml
1151 C:
1152 C:
1153 C:
1154 C: ]]>
1155 C:
1156 C:
1157 C: END
1158 S: RPY 0 1 . 110 181
1159 S: Content-Type: text/xml
1160 S:
1161 S:
1162 S: version attribute
1163 S: poorly formed in <ready> element
1164 S:
1165 S: END
1167 In this case, a positive reply is sent (as channel creation
1168 succeeded), but the encapsulated response contains an indication as
1169 to why the operation failed.
1171 3.1.2 Message Syntax
1173 Section 7.2 defines the messages that are used in the TLS transport
1174 security profile.
1176 3.1.3 Message Semantics
1178 3.1.3.1 The Ready Message
1180 The "ready" element has an optional "version" attribute and no
1181 content:
1183 o the "version" element defines the earliest version of TLS
1184 acceptable for use.
1186 When a BEEP peer sends the "ready" element, it must not send any
1187 further traffic on any channel until a corresponding reply is
1188 received; similarly, before processing a "ready" element, the
1189 receiving BEEP peer waits until any pending replies have been
1190 generated and sent.
1192 3.1.3.2 The Proceed Message
1194 The "proceed" element has no attributes and no content. It is sent
1195 as a reply to the "ready" element. When a BEEP peer receives the
1196 "ready" element, it begins the underlying negotiation process for
1197 transport security.
1199 4. User Authentication
1201 When a BEEP session is established, anonymous access, without trace
1202 information, is provided. Accordingly, user authentication in BEEP
1203 is achieved using an initial tuning profile.
1205 This document defines a family of profiles based on SASL mechanisms:
1207 o each mechanism in the IANA SASL registry[13] has an associated
1208 profile.
1210 Other profiles may be defined and deployed on a bilateral basis.
1212 Whenever a successful authentication occurs, on any channel, the
1213 authenticated identity is updated for all existing and future
1214 channels on the BEEP session; further, no additional attempts at
1215 authentication are allowed.
1217 Note that regardless of transport security and user authentication,
1218 authorization is an internal matter for each BEEP peer. As such,
1219 each peer may choose to restrict the operations it allows based on
1220 the authentication credentials provided (i.e., unauthorized
1221 operations might be rejected with error code 530).
1223 4.1 The SASL Family of Profiles
1225 Section 6.3 contains the registration for this profile.
1227 Note that SASL may provide both user authentication and transport
1228 security. Once transport security is successfully negotiated for a
1229 BEEP session, then a SASL security layer must not be negotiated;
1230 similarly, once any SASL negotiation is successful, a transport
1231 security profile must not begin its underlying negotiation process.
1233 Section 4 of the SASL specification[4] requires the following
1234 information be supplied by a protocol definition:
1236 service name: "beep"
1238 initiation sequence: Creating a channel using a BEEP profile
1239 corresponding to a SASL mechanism starts the exchange. An
1240 optional parameter corresponding to the "initial response" sent
1241 by the client is carried within a "blob" element during channel
1242 creation.
1244 exchange sequence: "Challenges" and "responses" are carried in
1245 exchanges of the "blob" element. The "status" attribute of the
1246 "blob" element is used both by a server indicating a successful
1247 completion of the exchange, and a client aborting the exchange,
1248 The server indicates failure of the exchange by sending an
1249 "error" element.
1251 security layer negotiation: When a security layer starts
1252 negotiation, all channels (including channel zero) are closed on
1253 the BEEP session. Accordingly, upon completion of the negotiation
1254 process, regardless of its outcome, a new greeting is issued by
1255 both BEEP peers.
1257 If a security layer is successfully negotiated, it takes effect
1258 immediately following the message that concludes the server's
1259 successful completion reply.
1261 use of the authorization identity: This is made available to all
1262 channels for the duration of the BEEP session.
1264 4.1.1 Profile Identification and Initialization
1266 Each SASL mechanism registered with the IANA is identified as:
1268 http://xml.resource.org/profiles/sasl/MECHANISM
1270 where "MECHANISM" is the token assigned to that mechanism by the
1271 IANA.
1273 Note that during channel creation, a BEEP peer may provide multiple
1274 profiles to the remote peer, e.g.,
1276 C: MSG 0 1 . 40 197
1277 C: Content-Type: text/xml
1278 C:
1279 C:
1280 C:
1282 C:
1283 C:
1284 C: END
1285 S: RPY 0 1 . 252 87
1286 S: Content-Type: text/xml
1287 S:
1288 S:
1289 S: END
1291 During channel creation, the corresponding "profile" element in the
1292 BEEP "start" element may contain a "blob" element. Note that it is
1293 possible for the channel to be created, but for the encapsulated
1294 operation to fail, e.g.,
1296 C: MSG 0 1 . 40 183
1297 C: Content-Type: text/xml
1298 C:
1299 C:
1300 C:
1301 C: AGJsb2NrbWFzdGVy]]>
1302 C:
1303 C:
1304 C: END
1305 S: RPY 0 1 . 252 166
1306 S: Content-Type: text/xml
1307 S:
1308 S:
1309 S: authentication mechanism is
1310 S: too weak
1311 S:
1312 S: END
1314 In this case, a positive reply is sent (as channel creation
1315 succeeded), but the encapsulated response contains an indication as
1316 to why the operation failed.
1318 Otherwise, the server sends a challenge (or signifies success), e.g.,
1320 C: MSG 0 1 . 40 183
1321 C: Content-Type: text/xml
1322 C:
1323 C:
1324 C:
1325 C: AGJsb2NrbWFzdGVy]]>
1326 C:
1327 C:
1328 C: END
1329 S: RPY 0 1 . 252 171
1330 S: Content-Type: text/xml
1331 S:
1332 S:
1333 S: b3RwLXNoYTEgOTk5NyBwaXh5bWlzYXM4NTgwNSBleHQ=
1334 ]]>
1335 S:
1336 S: END
1338 Note that this example implies that the "blob" element in the
1339 server's reply appears on two lines -- this is an artifact of the
1340 presentation; in fact, only one line is used.
1342 If a challenge is received, then the client responds and awaits
1343 another reply, e.g.,
1345 C: MSG 1 0 . 0 85
1346 C: Content-Type: text/xml
1347 C:
1348 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n
1349 C: END
1350 S: RPY 1 0 . 0 54
1351 S: Content-Type: text/xml
1352 S:
1353 S:
1354 S: END
1356 Of course, the client could abort the authentication process by
1357 sending "" instead.
1359 Alternatively, the server might reject the response with an error:
1360 e.g.,
1362 C: MSG 1 0 . 0 85
1363 C: Content-Type: text/xml
1364 C:
1365 C: d29yZDpmZXJuIGhhbmcgYnJvdyBib25nIGhlcmQgdG9n
1366 C: END
1367 S: ERR 1 1 . 0 48
1368 S: Content-Type: text/xml
1369 S:
1370 S:
1371 S: END
1373 Finally, depending on the SASL mechanism, an initialization element
1374 may be exchanged unidirectionally during channel creation, e.g.,
1376 C: MSG 0 1 . 40 133
1377 C: Content-Type: text/xml
1378 C:
1379 C:
1380 C:
1382 C:
1383 C: END
1384 S: RPY 0 1 . 252 173
1385 S: Content-Type: text/xml
1386 S:
1387 S:
1388 S: PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+
1389
1390 S:
1391 S: END
1393 Note that this example implies that the "blob" element in the
1394 server's reply appears on two lines -- this is an artifact of the
1395 presentation; in fact, only one line is used.
1397 4.1.2 Message Syntax
1399 Section 7.3 defines the messages that are used for each profile in
1400 the SASL family.
1402 Note that because many SASL mechanisms exchange binary data, the
1403 content of the "blob" element is always a base64-encoded string.
1405 4.1.3 Message Semantics
1407 The "blob" element has an optional "status" attribute, and arbitrary
1408 octets as its content:
1410 o the "status" attribute, if present, takes one of three values:
1412 abort: used by a client to indicate that it is aborting the
1413 authentication process;
1415 complete: used by a server to indicate that the exchange is
1416 complete and successful; or,
1418 continue: used by either a client or server, otherwise.
1420 Finally, note that SASL's EXTERNAL mechanism works with an "external
1421 authentication" service, which is provided by one of:
1423 o a transport security profile, capable of providing authentication
1424 information (e.g., Section 3.1), being active on the connection;
1426 o a network service, capable of providing strong authentication
1427 (e.g., IPSec[11]), underlying the connection; or,
1429 o a locally-defined security service.
1431 For authentication to succeed, two conditions must hold:
1433 o an external authentication service must be active; and,
1435 o if present, the authentication identity must be consistent with
1436 the credentials provided by the external authentication service
1437 (if the authentication identity is empty, then an authorization
1438 identity is automatically derived from the credentials provided
1439 by the external authentication service).
1441 5. Registration Templates
1443 5.1 Profile Registration Template
1445 When a profile is registered, the following information is supplied:
1447 Profile Identification: specify a URI[9] that authoritatively
1448 identifies this profile.
1450 Message Exchanged during Channel Creation: specify the datatypes
1451 that may be exchanged during channel creation.
1453 Messages starting one-to-one exchanges: specify the datatypes that
1454 may be present when an exchange starts.
1456 Messages in positive replies: specify the datatypes that may be
1457 present in a positive reply.
1459 Messages in negative replies: specify the datatypes that may be
1460 present in a negative reply.
1462 Messages in one-to-many exchanges: specify the datatypes that may be
1463 present in a one-to-many exchange.
1465 Message Syntax: specify the syntax of the datatypes exchanged by the
1466 profile.
1468 Message Semantics: specify the semantics of the datatypes exchanged
1469 by the profile.
1471 Contact Information: specify the postal and electronic contact
1472 information for the author of the profile.
1474 5.2 Feature Registration Template
1476 When a feature for the channel management profile is registered, the
1477 following information is supplied:
1479 Feature Identification: specify a string that identifies this
1480 feature. Unless the feature is registered with the IANA, the
1481 feature's identification MUST start with "x-".
1483 Feature Semantics: specify the semantics of the feature.
1485 Contact Information: specify the postal and electronic contact
1486 information for the author of the feature.
1488 6. Initial Registrations
1490 6.1 Registration: BEEP Channel Management
1492 Profile Identification: not applicable
1494 Messages exchanged during Channel Creation: not applicable
1496 Messages starting one-to-one exchanges: "start" or "close"
1498 Messages in positive replies: "greeting", "profile", or "ok"
1500 Messages in negative replies: "error"
1502 Messages in one-to-many exchanges: none
1504 Message Syntax: c.f., Section 7.1
1506 Message Semantics: c.f., Section 2.3.1
1508 Contact Information: c.f., the "Author's Address" section of this
1509 memo
1511 6.2 Registration: TLS Transport Security Profile
1513 Profile Identification: http://xml.resource.org/profiles/TLS
1515 Messages exchanged during Channel Creation: "ready"
1517 Messages starting one-to-one exchanges: "ready"
1519 Messages in positive replies: "proceed"
1521 Messages in negative replies: "error"
1523 Messages in one-to-many exchanges: none
1525 Message Syntax: c.f., Section 7.2
1527 Message Semantics: c.f., Section 3.1.3
1529 Contact Information: c.f., the "Author's Address" section of this
1530 memo
1532 6.3 Registration: SASL Family of Profiles
1534 Profile Identification:
1535 http://xml.resource.org/profiles/sasl/MECHANISM, where
1536 "MECHANISM" is a token registered with the IANA[14]
1538 Messages exchanged during Channel Creation: "blob"
1540 Messages starting one-to-one exchanges: "blob"
1542 Messages in positive replies: "blob"
1544 Messages in negative replies: "error"
1546 Messages in one-to-many exchanges: none
1548 Message Syntax: c.f., Section 7.3
1550 Message Semantics: c.f., Section 4.1.3
1552 Contact Information: c.f., the "Author's Address" section of this
1553 memo
1555 7. DTDs
1557 7.1 BEEP Channel Management DTD
1559
1569
1593
1594
1595
1596
1597
1598
1599
1611
1612
1616
1617
1621
1622
1623
1627
1628
1633
1635
1636
1640 7.2 TLS Transport Security Profile DTD
1642
1652
1660
1661
1664
1666 7.3 SASL Family of Profiles DTD
1668
1678
1686
1687
1693 8. Reply Codes
1695 code meaning
1696 ==== =======
1697 421 service not available
1699 450 requested action not taken
1700 (e.g., lock already in use)
1702 451 requested action aborted
1703 (e.g., local error in processing)
1705 454 temporary authentication failure
1707 500 general syntax error
1708 (e.g., poorly-formed XML)
1710 501 syntax error in parameters
1711 (e.g., non-valid XML)
1713 504 parameter not implemented
1715 530 authentication required
1717 534 authentication mechanism insufficient
1718 (e.g., too weak, sequence exhausted, etc.)
1720 535 authentication failure
1722 537 action not authorized for user
1724 538 authentication mechanism requires encryption
1726 550 requested action not taken
1727 (e.g., no requested profiles are acceptable)
1729 553 parameter invalid
1731 554 transaction failed
1732 (e.g., policy violation)
1734 9. Security Considerations
1736 The BEEP framing mechanism, per se, provides no protection against
1737 attack; however, judicious use of initial tuning profiles provides
1738 varying degrees of assurance:
1740 1. If one of the profiles from the SASL family is used, refer to
1741 [4]'s Section 9 for a discussion of security considerations.
1743 2. If the TLS transport security profile is used (or if a SASL
1744 security layer is negotiated), then:
1746 1. A man-in-the-middle may remove the security-related profiles
1747 from the BEEP greeting or generate a negative reply to the
1748 "ready" element of the TLS transport security profile. A
1749 BEEP peer may be configurable to refuse to proceed without
1750 an acceptable level of privacy.
1752 2. A man-in-the-middle may cause a down-negotiation to the
1753 weakest cipher suite available. A BEEP peer should be
1754 configurable to refuse weak cipher suites.
1756 3. A man-in-the-middle may modify any protocol exchanges prior
1757 to a successful negotiation. Upon completing the
1758 negotiation, a BEEP peer must discard previously cached
1759 information about the BEEP session.
1761 As different TLS ciphersuites provide varying levels of
1762 security, administrators should carefully choose which
1763 ciphersuites are provisioned.
1765 As BEEP is peer-to-peer in nature, before performing any task
1766 associated with a message, each channel should apply the appropriate
1767 access control based on the authenticated identity and privacy level
1768 associated with the BEEP session.
1770 References
1772 [1] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
1773 Extensions (MIME) Part One: Format of Internet Message
1774 Bodies", RFC 2045, November 1996.
1776 [2] World Wide Web Consortium, "Extensible Markup Language (XML)
1777 1.0", W3C XML, February 1998,
1778 .
1780 [3] Dierks, T., Allen, C., Treese, W., Karlton, P. L., Freier, A.
1781 O. and P. C. Kocher, "The TLS Protocol Version 1.0", RFC 2246,
1782 January 1999.
1784 [4] Myers, J.G., "Simple Authentication and Security Layer
1785 (SASL)", RFC 2222, October 1997.
1787 [5] Rose, M.T., "Mapping the BEEP Framework onto TCP",
1788 draft-ietf-beep-tcpmapping-04 (work in progress), October 2000.
1790 [6] Postel, J., "Transmission Control Protocol", RFC 793, STD 7,
1791 Sep 1981.
1793 [7] Crocker, D. H. and P. Overell, "Augmented BNF for Syntax
1794 Specifications: ABNF", RFC 2234, November 1997.
1796 [8] Alvestrand, H., "Tags for the Identification of Languages",
1797 RFC 1766, March 1995.
1799 [9] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform
1800 Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1801 1998.
1803 [10] Newman, C., "The One-Time-Password SASL Mechanism", RFC 2444,
1804 October 1998.
1806 [11] Kent, S. and R. Atkinson, "Security Architecture for the
1807 Internet Protocol", RFC 2401, November 1998.
1809 [12] Linn, J., "Generic Security Service Application Program
1810 Interface, Version 2", RFC 2078, January 1997.
1812 [13]
1815 [14]
1817 Author's Address
1819 Marshall T. Rose
1820 Invisible Worlds, Inc.
1821 1179 North McDowell Boulevard
1822 Petaluma, CA 94954-6559
1823 US
1825 Phone: +1 707 789 3700
1826 EMail: mrose@invisible.net
1827 URI: http://invisible.net/
1829 Appendix A. Acknowledgements
1831 The author gratefully acknowledges the contributions of: David
1832 Clark, Dave Crocker, Steve Deering, Wesley Michael Eddy, Marco
1833 Gazzetta, Danny Goodman, Steve Harris, Robert Herriot, Ken Hirsch,
1834 Greg Hudson, Ben Laurie, Carl Malamud, Michael Mealling, Keith
1835 McCloghrie, Paul Mockapetris, RL 'Bob' Morgan, Frank Morton, Darren
1836 New, Chris Newman, Joe Touch, Paul Vixie, Gabe Wachob, Daniel Woods,
1837 and, James Woodyatt. In particular, Dave Crocker provided helpful
1838 suggestions on the nature of segmentation in the framing mechanism.
1840 Appendix B. IANA Considerations
1842 The IANA registers "beep" as a GSSAPI[12] service name, as specified
1843 in Section 4.1.
1845 The IANA maintains a list of:
1847 o BEEP profiles, c.f., Section 5.1; and,
1849 o features for the channel management profile, c.f., Section 5.2.
1851 The IANA makes the registrations specified in Section 6.2 and
1852 Section 6.3. It is recommended that the IANA register these profiles
1853 using the IANA as a URI-prefix, and populate those URIs with the
1854 respective profile registrations.
1856 Full Copyright Statement
1858 Copyright (C) The Internet Society (2000). All Rights Reserved.
1860 This document and translations of it may be copied and furnished to
1861 others, and derivative works that comment on or otherwise explain it
1862 or assist in its implementation may be prepared, copied, published
1863 and distributed, in whole or in part, without restriction of any
1864 kind, provided that the above copyright notice and this paragraph
1865 are included on all such copies and derivative works. However, this
1866 document itself may not be modified in any way, such as by removing
1867 the copyright notice or references to the Internet Society or other
1868 Internet organizations, except as needed for the purpose of
1869 developing Internet standards in which case the procedures for
1870 copyrights defined in the Internet Standards process must be
1871 followed, or as required to translate it into languages other than
1872 English.
1874 The limited permissions granted above are perpetual and will not be
1875 revoked by the Internet Society or its successors or assigns.
1877 This document and the information contained herein is provided on an
1878 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1879 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1880 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1881 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1882 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1884 Acknowledgement
1886 Funding for the RFC editor function is currently provided by the
1887 Internet Society.