idnits 2.17.1 draft-nielsen-dime-02.txt: -(835): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories -- however, there's a paragraph with a matching beginning. Boilerplate error? == There are 4 instances of lines with non-ascii characters in the document. == 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 an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- -- 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 (June 17, 2002) is 7981 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) == Unused Reference: '12' is defined on line 1064, but no explicit reference was found in the text ** Obsolete normative reference: RFC 977 (ref. '1') (Obsoleted by RFC 3977) ** Obsolete normative reference: RFC 1652 (ref. '2') (Obsoleted by RFC 6152) ** Obsolete normative reference: RFC 1700 (ref. '3') (Obsoleted by RFC 3232) ** Obsolete normative reference: RFC 1869 (ref. '4') (Obsoleted by RFC 2821) ** Downref: Normative reference to an Informational RFC: RFC 1900 (ref. '5') ** Obsolete normative reference: RFC 2048 (ref. '8') (Obsoleted by RFC 4288, RFC 4289) ** Obsolete normative reference: RFC 2396 (ref. '10') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2434 (ref. '11') (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 2616 (ref. '12') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2717 (ref. '13') (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2718 (ref. '14') (Obsoleted by RFC 4395) ** Obsolete normative reference: RFC 2732 (ref. '15') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 3023 (ref. '16') (Obsoleted by RFC 7303) -- Possible downref: Non-RFC (?) normative reference: ref. '17' Summary: 18 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Henrik Frystyk Nielsen 3 draft-nielsen-dime-02 Henry Sanders 4 Microsoft, 5 Russell Butek 6 Simon Nash 7 IBM 9 Expires December 2002 June 17, 2002 11 Direct Internet Message Encapsulation (DIME) 13 Status of this Memo 15 This document is an Internet-Draft and is subject to all provisions 16 of Section 10 of RFC2026. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six 24 months and may be updated, replaced, or obsoleted by other 25 documents at any time. It is inappropriate to use Internet-Drafts 26 as reference material or to cite them other than as "work in 27 progress." 29 The list of current Internet-Drafts can be accessed at 30 "http://www.ietf.org/ietf/1id-abstracts.txt" 32 The list of Internet-Draft Shadow Directories can be accessed at 33 "http://www.ietf.org/shadow.html". 35 Please send comments to the "dime@discuss.develop.com" mailing 36 list, which is archived at "http://discuss.develop.com/dime.html". 38 Abstract 40 Direct Internet Message Encapsulation (DIME) is a lightweight, 41 binary message format that can be used to encapsulate one or more 42 application-defined payloads of arbitrary type and size into a 43 single message construct. Each payload is described by a type, a 44 length, and an optional identifier. Both URIs and MIME media type 45 constructs are supported as type identifiers. The payload length is 46 an integer indicating the number of octets of the payload. The 47 optional payload identifier is a URI enabling cross-referencing 48 between payloads. DIME payloads may include nested DIME messages or 49 chains of linked chunks of unknown length at the time the data is 50 generated. DIME is strictly a message format: it provides no 51 concept of a connection or of a logical circuit, nor does it 52 address head-of-line problems. 54 Table of Contents 56 1 Introduction................................................3 57 1.1 Notational Conventions...................................4 58 1.2 Conformance Requirement..................................4 59 1.3 Design Goals.............................................4 60 1.4 DIME Terminology.........................................5 61 1.5 Intended Usage...........................................7 62 2 The DIME Mechanisms.........................................8 63 2.1 DIME Encapsulation Constructs............................8 64 2.1.1 Message................................................8 65 2.1.2 Record.................................................9 66 2.1.3 Record Chunks..........................................9 67 2.2 DIME Version Number.....................................10 68 2.3 DIME Payload Description................................10 69 2.3.1 Payload Length........................................10 70 2.3.2 Payload Type..........................................11 71 2.3.3 Payload Identification................................12 72 2.4 DIME Options............................................12 73 3 The DIME Specifications....................................13 74 3.1 Data Transmission Order.................................13 75 3.2 Record Layout...........................................14 76 3.2.1 Version...............................................15 77 3.2.2 MB (Message Begin)....................................15 78 3.2.3 ME (Message End)......................................15 79 3.2.4 CF (Chunk Flag).......................................15 80 3.2.5 TYPE_T................................................15 81 3.2.6 RESRVD................................................17 82 3.2.7 OPTIONS_LENGTH........................................17 83 3.2.8 ID_LENGTH.............................................17 84 3.2.9 TYPE_LENGTH...........................................17 85 3.2.10 DATA_LENGTH...........................................17 86 3.2.11 OPTIONS...............................................18 87 3.2.12 ID....................................................18 88 3.2.13 TYPE..................................................19 89 3.2.14 DATA..................................................19 90 3.3 Use of URIs in DIME.....................................20 91 4 Internationalization Considerations........................20 92 5 Security Considerations....................................21 93 6 IANA Considerations........................................21 94 6.1 Media Type Registration: application/dime...............21 95 6.2 Guidelines for Registration of DIME Option Element Types23 96 7 Intellectual Property......................................24 97 8 Acknowledgements...........................................24 98 9 References.................................................24 99 10 Authors' Addresses.........................................26 100 1 Introduction 102 Direct Internet Message Encapsulation (DIME) is a lightweight, 103 binary message format designed to encapsulate one or more 104 application-defined payloads into a single message construct. A 105 DIME message contains one or more DIME records each carrying a 106 payload of arbitrary type and up to 2^32-1 octets in size. Records 107 can be chained together to support larger payloads. A DIME record 108 carries three parameters for describing its payload: the payload 109 length, the payload type, and an optional payload identifier. The 110 purpose of these parameters is as follows: 112 The payload length 114 The payload length indicates the number of octets in the 115 payload (see section 2.3.1). By providing the payload length 116 within the first 12 octets of a record, efficient record 117 boundary detection is possible. 119 The payload type 121 The DIME payload type identifier indicates the type of the 122 payload. DIME supports both URIs [10] as well as MIME media 123 type constructs [7] as type identifiers (see section 2.3.2). 124 By indicating the type of a payload, it is possible to 125 dispatch the payload to the appropriate user application. 127 The payload identifier 129 A payload may be given an optional identifier in the form of 130 an absolute or relative URI (see section 2.3.3). The use of an 131 identifier enables payloads that support URI linking 132 technologies to cross-reference other payloads. 134 In addition, each record contains a version number (see section 135 2.2) and a slot for optional data in the form of option elements 136 (see section 2.4). 138 1.1 Notational Conventions 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 142 this document are to be interpreted as described in RFC 2119 [9]. 144 1.2 Conformance Requirement 146 An implementation is not DIME compliant if it fails to satisfy one 147 or more of the MUST or REQUIRED level requirements defined in this 148 specification. A DIME implementation MUST be conformant in order to 149 parse or generate a DIME message defined by this specification. 151 1.3 Design Goals 153 Because of the large number of existing message encapsulation 154 formats, record marking protocols and multiplexing protocols, it is 155 best to be explicit about the design goals of DIME and, in 156 particular, about what is outside the scope of DIME. 158 The design goal of DIME is to provide an efficient and simple 159 message format that can accommodate the following: 161 1. Encapsulating arbitrary documents and entities, including 162 encrypted data, XML documents, XML fragments, image data like 163 GIF and JPEG files, etc. 165 2. Encapsulating documents and entities initially of unknown 166 size. This capability can be used to encapsulate dynamically 167 generated content or very large entities as a series of 168 chunks. 170 3. Aggregating multiple documents and entities that are logically 171 associated in some manner into a single message. For example, 172 DIME can be used to encapsulate a SOAP message and a set of 173 attachments referenced from that SOAP message. 175 In order to achieve efficiency and simplicity, the mechanisms 176 provided by this specification have been deliberately limited to 177 serve these purposes. DIME has not been designed as a general 178 message description or document format such as MIME or XML. 179 Instead, DIME-based applications can take advantage of such formats 180 by encapsulating them in DIME messages. 182 The following list identifies what is outside the scope of DIME: 184 1. DIME does not make any assumptions about the types of payloads 185 that are carried within DIME messages or about the message 186 exchange patterns of such messages. 188 2. DIME does not in any way introduce the notion of a connection 189 or of a logical circuit (virtual or otherwise). 191 3. DIME does not attempt to deal with head-of-line blocking 192 problems that might occur when using stream-oriented protocols 193 like TCP. 195 1.4 DIME Terminology 197 DIME message 199 The basic message construct defined by this specification. A 200 DIME message contains one or more DIME records (see section 201 2.1.1). 203 DIME record 205 A DIME record contains a payload described by a type, a 206 length, and an optional identifier (see section 2.1.2). 208 DIME record chunk 210 A DIME record that has been marked as containing a chunk of a 211 payload rather than a full payload (see section 2.1.3). 213 DIME version 215 A number used to identify the format of a DIME record (see 216 section 2.2). 218 DIME payload 220 The data carried within a DIME record defined by a user 221 application. 223 DIME chunked payload 225 A payload that has been partitioned into multiple DIME record 226 chunks. This can be used to carry dynamically generated 227 content or very large entities that don't fit into a single 228 DIME record (see section 2.1.3). 230 DIME payload length 232 The size of the payload indicated in number of octets (see 233 section 2.3.1). 235 DIME payload type 237 An identifier that indicates the type of the payload. This 238 specification supports both URIs [10] as well as MIME media 239 type constructs [11] as type identifiers (see section 2.3.2). 241 DIME payload identifier 243 A URI that optionally can be used to identify a payload (see 244 section 2.3.3). 246 DIME options 248 A DIME record might contain zero or more optional pieces of 249 data in the form of DIME option elements. This can be used to 250 carry additional information about the payload or information 251 which otherwise may be of benefit to the DIME parser parsing 252 the DIME message (see section 2.4). 254 DIME option element 256 An optional piece of data that may be carried in a DIME record 257 as part of the DIME options (see section 2.4). 259 DIME user application 261 The logical, higher-layer application that uses DIME for 262 encapsulating messages. 264 DIME generator 266 An entity or module that encapsulates user application-defined 267 payloads within DIME messages. 269 DIME parser 271 An entity or module that parses DIME messages and hands off 272 the payloads to a DIME user application. 274 1.5 Intended Usage 276 The intended usage of DIME is as follows: A user application wants 277 to encapsulate one or more related documents into a single DIME 278 message. For example, this can be a SOAP message along with a set 279 of attachments. The DIME generator encapsulates each document in 280 DIME records as payload or chunked payload, indicating the type and 281 length of the payload along with an optional identifier. The DIME 282 records are then put together to form a single DIME message. The 283 DIME parser deconstructs the DIME message and hands the payloads to 284 a (potentially different) user application. 286 DIME can be used in combination with most protocols that support 287 the exchange of binary data as long as the DIME message can be 288 exchanged in its entirety. A DIME message can be carried as a MIME 289 entity using the media type "application/dime" (see section 6 for 290 IANA media type registration of "application/dime"). 292 DIME records can encapsulate documents of any type. It is possible 293 to carry MIME messages in DIME records by using a media type such 294 as "message/rfc822". A DIME message can be encapsulated in a DIME 295 record by using the media type "application/dime" (see section 6). 297 It is important to note that although MIME entities are supported, 298 there are no assumptions in DIME that a record payload is MIME; 299 DIME makes no assumption concerning the type of the payloads 300 carried in a DIME message. 302 DIME provides no support for error handling. It is up to the DIME 303 parser to determine the implications of receiving a malformed DIME 304 message not conforming to this specification (see section 2.2 for a 305 description of DIME version numbers). It is the responsibility of 306 the user applications involved to provide any additional 307 functionality such as QoS that they may need as part of the overall 308 system in which they participate. 310 2 The DIME Mechanisms 312 This section describes the mechanisms used in DIME. The specific 313 syntax for these mechanisms is defined in section 3. 315 2.1 DIME Encapsulation Constructs 317 2.1.1 Message 319 A DIME message is composed of one or more DIME records. The first 320 record in a message is marked with the MB (Message Begin) flag set 321 and the last record in the message is marked with the ME (Message 322 End) flag set (see section 3.2.1 and 3.2.3). The minimum message 323 length is one record which is achieved by setting both the MB and 324 the ME flag in the same record. Note that at least two record 325 chunks are required in order to encode a chunked payload (see 326 section 2.1.3). The maximum number of DIME records that can be 327 carried in a DIME message is unbounded. 329 DIME messages MUST NOT overlap; that is, the MB and the ME flags 330 MUST NOT be used to nest DIME messages. DIME messages can be nested 331 by carrying a full DIME message within a DIME record with the type 332 "application/dime" (see section 6). 334 <--------------------- DIME message ----------------------> 335 +---------+ +---------+ +---------+ +---------+ 336 | R1 MB=1 | ... | Rr | ... | Rs | ... | Rt ME=1 | 337 +---------+ +---------+ +---------+ +---------+ 339 Figure 1: Example of a DIME message with a set of records. 340 The message head is to the left and the tail to the right, 341 with the logical record indexes t > s > r > 1. The MB 342 (Message Begin) flag is set in the first record (index 1) 343 and the ME (Message End) flag is set in the last record 344 (index t). 346 Note that actual DIME records do not carry an index number; the 347 ordering is implicitly given by the order in which the records are 348 serialized. 350 2.1.2 Record 352 A record is the unit for carrying a payload within a DIME message. 353 Each payload is described by its own set of parameters (see section 354 2.3). 356 2.1.3 Record Chunks 358 A record chunk is a DIME record that contains a chunk of a payload. 359 Chunked payloads can be used to partition dynamically generated 360 content or very large entities into multiple subsequent record 361 chunks serialized within the same DIME message. 363 Chunking is not a mechanism for introducing multiplexing into DIME. 364 It is a mechanism to limit the need for outbound buffering on the 365 generating side. This is similar to the message chunking mechanism 366 defined in HTTP/1.1 [11]. 368 A DIME message can contain zero or more chunked payloads. A chunked 369 payload is encoded as an initial record chunk followed by zero or 370 more middle record chunks followed by a terminating record chunk. 371 Each record chunk is encoded using the following encoding rules: 373 1. The initial record chunk is a DIME record with the CF (Chunk 374 Flag) flag set (see section 3.2.4). The type of the entire 375 chunked payload MUST be indicated in the TYPE field regardless 376 of whether the DATA_LENGTH field value is zero or not. The ID 377 field MAY be used to carry an identifier of the entire chunked 378 payload. The DATA_LENGTH field indicates the size of the data 379 carried in the DATA field (see section 2.3.1). 381 2. Each middle record chunk is a DIME record with the CF flag set 382 indicating that this record chunk contains the next chunk of 383 data of the same type and with the same identifier as the 384 initial record chunk. The value of the TYPE_LENGTH and the 385 ID_LENGTH fields MUST be zero and the TYPE_T field value MUST 386 be 0x00 (see section 3.2.8). The DATA_LENGTH field indicates 387 the size of the data carried in the DATA field (see section 388 2.3.1). 390 3. The terminating record chunk is a DIME record with the CF flag 391 cleared indicating that this record chunk contains the last 392 chunk of data of the same type and with the same identifier as 393 the initial record chunk. As with the middle record chunks, 394 the value of the TYPE_LENGTH and the ID_LENGTH fields MUST be 395 zero and the TYPE_T field value MUST be 0x00 (see section 396 3.2.8). The DATA_LENGTH field indicates the size of the data 397 carried in DATA field (see section 2.3.1). 399 A chunked payload MUST be entirely encapsulated within a single 400 DIME message. That is, a chunked payload MUST NOT span multiple 401 DIME messages. As a result, neither an initial nor a middle record 402 chunk can have the ME (Message End) flag set. 404 2.2 DIME Version Number 406 A DIME record contains a version number that indicates the format 407 of the record. The DIME version number is incremented when the 408 format of a DIME message is changed. Version numbers are considered 409 to be "major" rather than "minor". That is, there is no assumption 410 of compatibility between any two versions. 412 All DIME records in a DIME message including record chunks MUST be 413 of the same version. A DIME parser encountering different DIME 414 version numbers in different DIME records in the same DIME message 415 MUST discard that message as faulty. 417 In order to parse a DIME record of a given version, a DIME parser 418 MUST be compliant with that version (see section 1.2). A DIME 419 implementation MUST NOT attempt to parse or generate a DIME record 420 with a version that the implementation does not comply with. A DIME 421 implementation MAY but NEED NOT support multiple DIME versions. 423 This document defines version 1 (0x01) (see section 3.2.1). Any new 424 version of DIME MUST be published as a standard-track RFC following 425 IETF consensus. 427 2.3 DIME Payload Description 429 Each record contains information about the payload carried within 430 it. This section introduces the mechanisms by which these payloads 431 are described. 433 2.3.1 Payload Length 435 Regardless of the relationship of a record to other records, the 436 payload length always indicates the length of the payload 437 encapsulated in THIS record. The length of the payload is indicated 438 in number of octets in the DATA_LENGTH field (see section 3.2.10). 439 Note that zero is a valid length. 441 2.3.2 Payload Type 443 The payload type of a record indicates the kind of data being 444 carried in the payload of that record. This may be used to guide 445 the processing of the payload at the discretion of the user 446 application. The type of the first record, by convention, provides 447 the processing context not only for the first record but for the 448 whole DIME message. Additional context for processing the message 449 may be provided by the transport service port (TCP, UDP, etc) at 450 which the message was received and by other communication 451 parameters. 453 It is important to emphasize that DIME mandates no specific 454 processing model for DIME messages. The usage of the payload types 455 is entirely at the discretion of the user application. The comments 456 regarding usage above should be taken as guidelines for building 457 processing conventions, including mappings of higher level 458 application semantics onto DIME. 460 The structure and format of the TYPE field value is indicated using 461 the TYPE_T field (see section 3.2.5). This specification supports 462 TYPE field values in the form of absolute URIs and MIME media type 463 constructs. The former allows for decentralized control of the 464 value space and the latter allows DIME to take advantage of the 465 already very large and successful media type value space maintained 466 by IANA [3]. 468 The media type registration process is outlined in RFC 2048 [8]. 469 Use of non-registered media types is discouraged. The URI scheme 470 registration process is described in RFC 2717 [13]. It is 471 recommended that only well-known URI schemes registered by IANA be 472 used (see [17] for a current list). 474 URIs can be used for message types that are defined by URIs. 475 Records that carry a payload with an XML-based message type MAY use 476 the XML namespace identifier of the root element as the TYPE field 477 value. A SOAP/1.1 message, for example, may be represented by the 478 URI 480 http://schemas.xmlsoap.org/soap/envelope/ 482 Records that carry a payload with an existing, registered media 483 type SHOULD carry a TYPE field value of that media type. Note that 484 the TYPE field indicates the type of the payload; it does NOT refer 485 to a MIME message that contains an entity of the given type. For 486 example, the media type 487 image/jpeg 489 indicates that the payload is a JPEG image. Similarly, the media 490 type 492 message/http 494 indicates that the payload is an HTTP message as defined by RFC 495 2616 [11]. A value of 497 application/xml; charset="utf-16" 499 indicates that the payload is an XML document as defined by RFC 500 3023 [16]. 502 2.3.3 Payload Identification 504 The optional payload identifier allows user applications to 505 identify a payload within a DIME record. By providing a payload 506 identifier, it becomes possible for other payloads supporting URI- 507 based linking technologies to refer to that payload. DIME does not 508 mandate any particular linking mechanism but leaves this to the 509 user application to define in the language it prefers. 511 It is important that payload identifiers are maintained so that 512 references to those payloads are not broken. If records are 513 repackaged, for example, by an intermediate application, then that 514 application MUST ensure that the payload identifiers are preserved. 516 2.4 DIME Options 518 DIME has provisions for carrying additional information in a DIME 519 record as option elements. A DIME record (including a record chunk) 520 can carry zero or more such option elements each containing 521 information about the payload or information which otherwise may be 522 of benefit to a DIME parser. 524 An option element contains two parameters describing its contents: 525 a type and a length. The meaning of these parameters is as follows: 527 o The option element type indicates the structure and format of 528 the data carried in that element (see section 3.2.11). 530 o The option element length indicates the size of the data 531 carried in that element in number of octets (see section 532 3.2.11). 534 The structure and format of each element is entirely determined by 535 the option element type. This specification does not define any 536 option element types. DIME option elements are defined in a 537 centralized manner controlled by IANA (see section 6.2 for IANA 538 guidelines). 540 Option elements are set on a per DIME record basis. A DIME 541 generator MAY generate different option elements for different DIME 542 records in the same DIME message. Use of option data is OPTIONAL by 543 DIME generators. 545 DIME option element types are defined independently of each other; 546 support for an element type does not imply support for other 547 element types. That is, a DIME parser that recognizes option 548 element type 5 might not recognize type 4 or 6. 550 A DIME parser conforming to this specification MAY but NEED NOT 551 support any option element types. A DIME parser SHOULD ignore 552 unrecognized option element types. 554 3 The DIME Specifications 556 3.1 Data Transmission Order 558 The order of transmission of the DIME record described in this 559 document is resolved to the octet level. For diagrams showing a 560 group of octets, the order of transmission of those octets is first 561 left to right and then top to bottom, as they are read in English. 562 For example, in the diagram in Figure 2, the octets are transmitted 563 in the order they are numbered. 565 0 1 2 3 566 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 567 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 568 | Octet 1 | Octet 2 | Octet 3 | Octet 4 | 569 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 570 | Octet 5 | Octet 6 | Octet 7 | Octet 8 | 571 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 573 Figure 2: DIME octet ordering 574 Whenever an octet represents a numeric quantity, the leftmost bit 575 in the diagram is the high order or most significant bit. That is, 576 the bit labeled 0 is the most significant bit. 578 For each multi-octet field representing a numeric quantity defined 579 by DIME, the leftmost bit of the whole field is the most 580 significant bit. Such quantities are transmitted in a big-endian 581 manner with the most significant octet transmitted first. 583 3.2 Record Layout 585 DIME records are variable length records with a common format 586 illustrated in Figure 3. In the following sections, the individual 587 record fields are described in more detail. 589 0 1 2 3 590 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 591 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 592 | |M|M|C| | | | 593 | VERSION |B|E|F| TYPE_T| RESRVD| OPTIONS_LENGTH | 594 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 595 | ID_LENGTH | TYPE_LENGTH | 596 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 597 | DATA_LENGTH | 598 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 599 | / 600 / OPTIONS + PADDING / 601 / | 602 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 603 | / 604 / ID + PADDING / 605 / | 606 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 607 | / 608 / TYPE + PADDING / 609 / | 610 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 611 | / 612 / DATA + PADDING / 613 / | 614 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 616 Figure 3: DIME Record Layout. The use of "/" indicates a 617 field length which is a multiple of 4 octets. 619 3.2.1 Version 621 An unsigned 5-bit integer that indicates the format of the DIME 622 record (see section 2.2). This document defines version 1 (0x01). A 623 DIME generator conforming to this specification MUST generate DIME 624 messages with a VERSION field value of 0x01. A DIME parser 625 conforming to this specification MUST verify that the VERSION field 626 has a value of 0x01. 628 3.2.2 MB (Message Begin) 630 The MB flag is a 1 bit field that when set indicates the start of a 631 DIME message (see section 2.1.1). 633 3.2.3 ME (Message End) 635 The ME flag is a 1 bit field that when set indicates the end of a 636 DIME message (see section 2.1.1). Note, that in case of a chunked 637 payload, the ME flag is set only in the terminating record chunk of 638 the last chunked payload (see section 2.1.3). 640 3.2.4 CF (Chunk Flag) 642 The CF flag is a 1 bit field indicating that this is either the 643 first record chunk or a middle record chunk of a chunked payload 644 (see section 2.1.3 for a description of how to encode a chunked 645 payload). 647 3.2.5 TYPE_T 649 The TYPE_T field value indicates the structure and format of the 650 value of the TYPE field (see section 2.3.2 for a description of the 651 TYPE field and section 4 for a description of internationalization 652 issues related to the TYPE field). The TYPE_T field is a 4 bit 653 field with values defined in Table 1: 655 TYPE_T Value 657 Unchanged (see section 2.1.3) 0x00 659 media-type as defined in RFC 2616 [11] 0x01 661 absoluteURI as defined in RFC 2396 [10] 0x02 663 Unknown 0x03 665 None 0x04 667 Reserved 0x05-0x0F 669 Table 1: DIME TYPE_T field values. 671 The value 0x00 (Unchanged) MUST be used in all middle record chunks 672 and terminating record chunks used in chunked payloads (see section 673 2.1.3). It MUST NOT be used in any other record. When used, the 674 TYPE_LENGTH field value MUST be zero. 676 The value 0x01 (media-type) indicates that the TYPE field contains 677 a value that follows the "media-type" BNF construct defined by RFC 678 2616 [11] (see section 2.3.2). 680 The value 0x02 (absoluteURI) indicates that the TYPE field contains 681 a value that follows the "absoluteURI" BNF construct defined by RFC 682 2396 [10] (see section 2.3.2). 684 The value 0x03 (Unknown) SHOULD be used to indicate that the type 685 of the payload is unknown. This is similar to the 686 "application/octet-stream" media type defined by MIME [7]. When 687 used, the TYPE_LENGTH field value MUST be zero. Regarding 688 implementation, it is RECOMMENDED that a DIME parser receiving a 689 DIME record of this type provides a mechanism for storing but not 690 processing the payload (see section 5). 692 The value 0x04 (None) indicates that there is no type or payload 693 associated with this record. When used, the value of the 694 TYPE_LENGTH and the DATA_LENGTH fields MUST be zero. This TYPE_T 695 value can be used whenever an empty record is needed, for example 696 in order to terminate a DIME message in cases where there is no 697 payload defined by the user application. 699 There is no default value for the TYPE_T field. Reserved TYPE_T 700 field values are for future use and MUST NOT be used. A DIME parser 701 that receives a DIME record with an unknown TYPE_T field value 702 SHOULD treat the payload as if it had been marked with a value of 703 0x03 (Unknown). Note, that in this case the TYPE_LENGTH is not 704 required to be zero. 706 3.2.6 RESRVD 708 The RESRVD field is reserved for future use and MUST be set to 709 0x00. A DIME parser that receives a DIME record with a RESRVD field 710 value other than 0x00 MUST discard that message as faulty. 712 3.2.7 OPTIONS_LENGTH 714 An unsigned 16 bit integer that specifies the length in octets of 715 the OPTIONS field excluding any padding used to achieve a 4 octet 716 alignment of the OPTIONS field (see section 2.4). 718 3.2.8 ID_LENGTH 720 An unsigned 16 bit integer that specifies the length in octets of 721 the ID field excluding any padding used to achieve a 4 octet 722 alignment of the ID field (see section 2.3.3). 724 3.2.9 TYPE_LENGTH 726 An unsigned 16 bit integer that specifies the length in octets of 727 the TYPE field excluding any padding used to achieve a 4 octet 728 alignment of the TYPE field (see section 2.3.2). 730 3.2.10 DATA_LENGTH 732 The DATA_LENGTH field is an unsigned 32 bit integer that specifies 733 the length in octets of the DATA field excluding any padding used 734 to achieve a 4 octet alignment of the DATA field (see section 735 2.3.1). 737 A payload size of 0 octets is allowed. Payloads larger than 2^32-1 738 octets can be accommodated by using chunked payloads (see section 739 2.1.3). 741 3.2.11 OPTIONS 743 The OPTIONS field contains 0 or more option elements where each 744 element follows the layout in Figure 4 (see section 2.4 for a 745 description of option elements): 747 0 1 2 3 748 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 749 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 750 | ELEMENT_T | ELEMENT_LENGTH | 751 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 752 | / 753 / ELEMENT_DATA / 754 / | 755 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 757 Figure 4: DIME option element layout. The use of "/" 758 indicates a field length which is a multiple of 4 octets. 760 All DIME records MAY have a non-zero OPTIONS field. A DIME parser 761 receiving a DIME record with an unrecognized option element type 762 SHOULD ignore that element (see section 6.2 for IANA guidelines for 763 registration of new option element types). 765 The length of each element does not have to be a multiple of 4 766 octets and there is no padding between elements. However, the size 767 of the OPTIONS field MUST be a multiple of 4 octets. If the length 768 of all the elements is not a multiple of 4 octets, the generator 769 MUST pad the OPTIONS field value with all zero octets. Padding is 770 not included in the OPTIONS_LENGTH field (see section 3.2.7). 772 A DIME generator MUST NOT pad the OPTIONS field with more than 3 773 octets. A DIME parser MUST ignore the padding octets. 775 3.2.12 ID 777 The value of the ID field is an identifier in the form of a URI 778 [10] (see section 2.3.3 and 3.3). The required uniqueness of the 779 message identifier is guaranteed by the generator. The URI can be 780 either relative or absolute; DIME does not define a base URI which 781 means that user applications using relative URIs MUST provide an 782 actual or a virtual base URI (see [10]). 784 With the exception of subsequent record chunks (see section 2.1.3), 785 all records MAY have a non-zero ID field. 787 The length of the ID field MUST be a multiple of 4 octets. If the 788 length of the payload id value is not a multiple of 4 octets, the 789 generator MUST pad the value with all zero octets. Padding is not 790 included in the ID_LENGTH field (see section 3.2.8). 792 A DIME generator MUST NOT pad the ID field with more than 3 octets. 793 A DIME parser MUST ignore the padding octets. 795 3.2.13 TYPE 797 The value of the TYPE field is an identifier describing the type of 798 the payload (see section 2.3.2). The value of the TYPE field MUST 799 follow the structure implied by the value of the TYPE_T field (see 800 section 3.2.5). 802 The length of the TYPE field MUST be a multiple of 4 octets. If the 803 length of the payload type value is not a multiple of 4 octets, the 804 generator MUST pad the value with all zero octets. Padding is not 805 included in the TYPE_LENGTH field (see section 3.2.9). 807 A DIME generator MUST NOT pad the TYPE field with more than 3 808 octets. A DIME parser MUST ignore the padding octets. 810 A DIME parser receiving a DIME record with a known TYPE_T field 811 value but an unknown TYPE field value SHOULD interpret the type 812 identifier of that record as if the TYPE_T field value was 0x03 813 (Unknown). 815 It is STRONGLY RECOMMENDED that the identifier be globally unique 816 and maintained with stable and well-defined semantics over time. 818 3.2.14 DATA 820 The DATA field carries the payload intended for the DIME user 821 application. Any internal structure of the data carried within the 822 DATA field is opaque to DIME. 824 The length of the DATA field MUST be a multiple of 4 octets. If the 825 length of the payload is not a multiple of 4 octets, the generator 826 MUST pad the value with all zero octets. Padding is not included in 827 the DATA_LENGTH field (see section 3.2.10). 829 A DIME generator MUST NOT pad the DATA field with more than 3 830 octets. A DIME parser MUST ignore the padding octets. 832 3.3 Use of URIs in DIME 834 DIME uses URIs [10] for some identifiers. To DIME, a URI is simply 835 a formatted string that identifies�via name, location, or any other 836 characteristic�a resource on the Web. 838 The use of IP addresses in URIs SHOULD be avoided whenever possible 839 (see RFC 1900 [5]). However, when used, the literal format for Ipv6 840 addresses in URIs as described by RFC 2732 [15] SHOULD be 841 supported. 843 DIME does not define any equivalence rules for URIs in general as 844 these are defined by the individual URI schemes and by RFC 2396 845 [10]. However, because of inconsistencies with respect to some URI 846 equivalence rules in many current URI parsers, it is STRONGLY 847 RECOMMENDED that generators of DIME messages only rely on the most 848 rudimentary equivalence rules defined by RFC 2396. 850 The size of URIs used as values in the ID field and the TYPE field 851 is limited by the maximum size of these fields which is 2^16-1 852 octets. DIME parsers and generators MUST be able to deal with URIs 853 of this size. 855 4 Internationalization Considerations 857 Identifiers used in DIME such as URIs and MIME media type 858 constructs provide different levels of support for 859 internationalization. It is STRONGLY RECOMMENDED that the 860 definitions and guidelines for internationalization support of 861 these values be followed when used in DIME. In particular, the 862 following fields require special attention: 864 o For the ID field, implementers are referred to RFC 2718 [14] 865 for internationalization considerations of URIs. 867 o For a TYPE_T value of 0x01 (media types), implementers are 868 referred to RFC 2046 [7] for internationalization 869 considerations of MIME media types. 871 o For a TYPE_T value of 0x02 (absolute URI), implementers are 872 referred to RFC 2718 [14] for internationalization 873 considerations of URIs. 875 For ELEMENT_T values and TYPE_T values not defined by this 876 specification, implementers are referred to the documentation of 877 such features for specific internationalization considerations. 879 5 Security Considerations 881 Implementers should pay special attention to the security 882 implications of any record types that can cause the remote 883 execution of any actions in the recipient's environment. Before 884 accepting records of any type, an application should be aware of 885 the particular security implications associated with that type. 887 Security considerations for media types in general are discussed in 888 RFC 2048 [8] and in the context of the "application/postscript" and 889 the "message/external-body" media type in RFC 2046 [7]. 891 Note: This specification does not presently define any 892 mechanisms for providing security for DIME messages and header 893 information. Future revisions of this specification will 894 address this open issue. 896 6 IANA Considerations 898 This draft describes a new media type, "application/dime" for which 899 section 6.1 contains a registration application following the 900 guidelines in RFC 2048 [8]. 902 Section 6.2 contains guidelines for definition and registration of 903 additional DIME options (see section 2.4). 905 6.1 Media Type Registration: application/dime 907 MIME media type name: application 908 MIME subtype name: dime 910 Required parameters: none 912 Optional parameters: none 914 Encoding considerations: 916 This media type MAY be encoded as appropriate for the charset 917 and the capabilities of the underlying MIME transport. For 7- 918 bit transports, data using 8-bit or higher MUST be encoded in 919 quoted-printable or base64 content-transfer-encodings. For 8- 920 bit clean transport (e.g., 8BITMIME [2] ESMTP [4] or NNTP 921 [1]), 8-bit data such as UTF-8 does not need to be encoded. 922 Over HTTP [11], no content-transfer-encoding is necessary 923 regardless of the encoding. 925 Security considerations: See section 5 927 Interoperability considerations: n/a 929 Published Specification: this specification 931 Applications which use this media type: 933 Applications that choose to use DIME as the packaging 934 mechanism for encapsulating one or more application-defined 935 payloads of arbitrary type and size into a single message 936 construct. 938 Additional information: none 940 Magic number(s): none 942 File extension(s): 944 .dim 945 .dime 946 Macintosh File Type Code(s): 948 DIME 950 Person and email address for further information: see section 10 952 Intended usage: 954 COMMON 956 Author/Change controller: 958 The DIME specification is an individual Internet Draft 959 submission. It is not the product of an IETF Working Group. 960 The IETF has change control over the DIME specification. 962 6.2 Guidelines for Registration of DIME Option Element Types 964 The registration process of DIME option element types follows the 965 guidelines for "IETF Consensus" as defined in RFC 2434 [11] where 966 new ELEMENT_T values are assigned through the IETF consensus 967 process. Specifically, new assignments are made via RFCs approved 968 by the IESG. Typically, the IESG will seek input on prospective 969 assignments from appropriate persons (e.g., a relevant Working 970 Group if one exists). 972 The following process is designed to ensure that new DIME option 973 elements are reviewed for technical correctness and appropriateness 974 and that their description is complete and published before an 975 ELEMENT_T value is assigned by IANA. 977 1. The author(s) document(s) the option element, leaving the 978 ELEMENT_T value as "To Be Determined" (TBD). It is important 979 that security and internationalization concerns for the option 980 element be addressed. It is STRONGLY RECOMMENED that the 981 documentation be published as an Internet Draft. 983 2. The author(s) submit(s) the Internet Draft for review by the 984 IESG and any relevant working groups (IETF or otherwise). 986 3. The specification of the new option element is reviewed by the 987 IESG, the IETF, and other relevant groups identified in 2). If 988 the option element is accepted for inclusion in the DIME 989 specification, the specification of the option is published as 990 either a standards-track or a non-standards-track RFC. 992 4. At the time of publication as an RFC, IANA assigns a DIME 993 ELEMENT_T value for the new option element. The option is not 994 to be used in published implementations before IANA has 995 assigned an ELEMENT_T value. 997 7 Intellectual Property 999 The following notice is copied from RFC 2026 [6], Section 10.4, and 1000 describes the position of the IETF concerning intellectual property 1001 claims made against this document. 1003 The IETF takes no position regarding the validity or scope of any 1004 intellectual property or other rights that might be claimed to 1005 pertain to the implementation or use other technology described in 1006 this document or the extent to which any license under such rights 1007 might or might not be available; neither does it represent that it 1008 has made any effort to identify any such rights. Information on 1009 the procedures of the IETF with respect to rights in standards- 1010 track and standards-related documentation can be found in BCP-11. 1011 Copies of claims of rights made available for publication and any 1012 assurances of licenses to be made available, or the result of an 1013 attempt made to obtain a general license or permission for the use 1014 of such proprietary rights by implementers or users of this 1015 specification can be obtained from the IETF Secretariat. 1017 The IETF invites any interested party to bring to its attention any 1018 copyrights, patents or patent applications, or other proprietary 1019 rights that may cover technology that may be required to practice 1020 this standard. Please address the information to the IETF Executive 1021 Director. 1023 8 Acknowledgements 1025 Special thanks go to Paul H. Gleichauf and Krishna Sankar of Cisco 1026 for their input on this specification. 1028 9 References 1030 [1] B. Kantor, P. Lapsley, "Network News Transfer Protocol", RFC 1031 977, U.C. San Diego, U.C. Berkeley, February 1986 1033 [2] J. Klensin, N. Freed, M. Rose, E. Stefferud, D. Crocker, 1034 "SMTP Service Extension for 8bit-MIMEtransport", RFC 1652, 1035 MCI, Innosoft, Dover Beach Consulting, Inc., Network 1036 Management Associates, Inc., Silicon Graphics, Inc., July 1037 1994. 1038 [3] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1039 1700, October 1994. 1040 [4] J. Klensin, N. Freed, M. Rose, E. Stefferud, D. Crocker, " 1041 SMTP Service Extensions", RFC 1869, MCI, Innosoft 1042 International, Inc., Dover Beach Consulting, Inc., Network 1043 Management Associates, Inc., Brandenburg Consulting, Inc., 1044 November 1995. 1045 [5] B. Carpenter, Y. Rekhter, "Renumbering Needs Work", RFC 1046 1900, IAB, February 1996 1047 [6] S. Bradner, "The Internet Standards Process � Revision 3", 1048 RFC 2026, Harvard University, October 1996 1049 [7] N. Freed, N. Borenstein, "Multipurpose Internet Mail 1050 Extensions (MIME) Part Two: Media Types" RFC 2046, Innosoft 1051 First Virtual, November 1996 1052 [8] N. Freed, J. Klensin, J. Postel, "Multipurpose Internet Mail 1053 Extensions (MIME) Part Four: Registration Procedures", RFC 1054 2048, Innosoft, MCI, ISI, November 1996 1055 [9] S. Bradner, "Key words for use in RFCs to Indicate 1056 Requirement Levels", RFC 2119, Harvard University, March 1057 1997 1058 [10] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource 1059 Identifiers (URI): Generic Syntax", RFC 2396, MIT/LCS, U.C. 1060 Irvine, Xerox Corporation, August 1998. 1061 [11] T. Narten, H. Alvestrand, "Guidelines for Writing an IANA 1062 Considerations Section in RFCs", BCP 26, RFC 2434, October 1063 1998. 1064 [12] R. Fielding, J. Gettys, J. C. Mogul, H. F. Nielsen, T. 1065 Berners-Lee, "Hypertext Transfer Protocol � HTTP/1.1", RFC 1066 2616, U.C. Irvine, DEC W3C/MIT, DEC, W3C/MIT, W3C/MIT, 1067 January 1997 1068 [13] R. Petke, I. King, "Registration Procedures for URL Scheme 1069 Names", BCP: 35, RFC 2717, UUNET Technologies, Microsoft 1070 Corporation, November 1999 1071 [14] L. Masinter, H. Alvestrand, D. Zigmond, R. Petke, 1072 "Guidelines for new URL Schemes", RFC 2718, Xerox 1073 Corporation, Maxware, Pirsenteret, WebTV Networks, Inc., 1074 UUNET Technologies, November 1999 1075 [15] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal 1076 Ipv6 Addresses in URL's", RFC 2732, Nokia, IBM, AT&T, 1077 December 1999 1078 [16] M. Murata, S. St.Laurent, D. Kohn, "XML Media Types" RFC 1079 3023, IBM Tokyo Research Laboratory, simonstl.com, Skymoon 1080 Ventures, January 2001 1081 [17] List of Uniform Resource Identifier (URI) schemes registered 1082 by IANA is available at 1083 "http://www.iana.org/assignments/uri-schemes" 1084 10 Authors' Addresses 1086 Henrik Frystyk Nielsen 1087 Microsoft 1088 One Microsoft Way, Redmond, WA 90852 1089 Email: henrikn@microsoft.com 1091 Henry Sanders 1092 Microsoft 1093 One Microsoft Way, Redmond, WA 90852 1094 Email: henrysa@microsoft.com 1096 Russell Butek 1097 IBM 1098 11501 Burnet Road, Austin, TX 78758 1099 Email: butek@us.ibm.com 1101 Simon Nash 1102 IBM 1103 Hursley Park, Winchester, UK 1104 Email: nash@hursley.ibm.com