1INTERNET-DRAFT S. Legg 2draft-legg-ldap-transfer-03.txt Adacel Technologies 3Intended Category: Standards Track 16 June 2004 4Updates: RFC 2252bis 5 6 7 Lightweight Directory Access Protocol (LDAP): 8 Transfer Encoding Options 9 10 Copyright (C) The Internet Society (2004). All Rights Reserved. 11 12 Status of this Memo 13 14 15 This document is an Internet-Draft and is in full conformance with 16 all provisions of Section 10 of RFC2026. 17 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 21 Internet-Drafts. 22 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress". 27 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 30 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 33 34 This document is intended to be, after appropriate review and 35 revision, submitted to the RFC Editor as a Standard Track document. 36 Distribution of this document is unlimited. Technical discussion of 37 this document should take place on the IETF LDAP Revision Working 38 Group (LDAPbis) mailing list <ietf-ldapbis@openldap.org>. Please 39 send editorial comments directly to the editor 40 <steven.legg@adacel.com.au>. 41 42 This Internet-Draft expires on 16 December 2004. 43 44 45Abstract 46 47 Each attribute stored in a Lightweight Directory Access Protocol 48 (LDAP) directory has a defined syntax (i.e., data type). A syntax 49 50 51 52Legg Expires 16 December 2004 [Page 1] 53 54INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 55 56 57 definition specifies how attribute values conforming to the syntax 58 are normally represented when transferred in LDAP operations. This 59 representation is referred to as the LDAP-specific encoding to 60 distinguish it from other methods of encoding attribute values. This 61 document introduces a new category of attribute options, called 62 transfer encoding options, which can be used to specify that the 63 associated attribute values are encoded according to one of these 64 other methods. 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108Legg Expires 16 December 2004 [Page 2] 109 110INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 111 112 113Table of Contents 114 115 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 116 2. Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . 3 117 3. Transfer Encoding Options. . . . . . . . . . . . . . . . . . . 4 118 4. Defined Transfer Encoding Options. . . . . . . . . . . . . . . 5 119 5. Attributes Returned in a Search. . . . . . . . . . . . . . . . 6 120 6. Syntaxes Requiring Binary Transfer . . . . . . . . . . . . . . 7 121 7. Security Considerations. . . . . . . . . . . . . . . . . . . . 7 122 8. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 8 123 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 124 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 125 9.2. Informative References . . . . . . . . . . . . . . . . . 10 126 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 127 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 10 128 1291. Introduction 130 131 Each attribute stored in a Lightweight Directory Access Protocol 132 (LDAP) directory [ROADMAP] has a defined syntax (i.e., data type) 133 which constrains the structure and format of its values. 134 135 The description of each syntax [SYNTAX] specifies how attribute or 136 assertion values [MODELS] conforming to the syntax are normally 137 represented when transferred in LDAP operations [PROT]. This 138 representation is referred to as the LDAP-specific encoding to 139 distinguish it from other methods of encoding attribute values. 140 141 This document introduces a new category of attribute options 142 [MODELS], called transfer encoding options, that allow attribute and 143 assertion values to be transferred using an alternative method of 144 encoding. This document defines several transfer encoding options 145 which can be used in an attribute description [MODELS] in an LDAP 146 operation to specify that the associated attribute values or 147 assertion value are, or are requested to be, encoded according to 148 specific Abstract Syntax Notation One (ASN.1) [X680] encoding rules, 149 instead of the usual LDAP-specific encoding. One option in 150 particular allows Extensible Markup Language (XML) [XML] encodings. 151 1522. Conventions 153 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 156 document are to be interpreted as described in BCP 14, RFC 2119 157 [KEYWORD]. 158 159 This specification makes use of definitions from the XML Information 160 Set (Infoset) [ISET]. In particular, information item property names 161 162 163 164Legg Expires 16 December 2004 [Page 3] 165 166INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 167 168 169 are presented per the Infoset, e.g., [local name]. 170 1713. Transfer Encoding Options 172 173 Transfer encoding options enable attribute and assertion values to be 174 transferred using an alternative method of encoding to the default 175 LDAP-specific encoding. In fact, some attribute and assertion 176 syntaxes do not have a defined LDAP-specific encoding in which case 177 the only way values of those syntaxes can be transferred is by using 178 an alternative encoding. 179 180 The binary option [BINARY] is not formally regarded as a transfer 181 encoding option, though it has much in common with transfer encoding 182 options. The requirements governing the use of transfer encoding 183 options do not apply to the binary option. The requirements 184 governing the use of the binary option are described elsewhere 185 [BINARY]. 186 187 In terms of the protocol [PROT], a transfer encoding option specifies 188 that the contents octets of an associated AttributeValue or 189 AssertionValue OCTET STRING are a complete encoding of the relevant 190 value according to the encoding method specified by the option. 191 192 Where a transfer encoding option is present in an attribute 193 description the associated attribute values or assertion value MUST 194 be encoded according to the encoding method corresponding to the 195 option. Note that it is possible for a syntax to be defined such 196 that its LDAP-specific encoding is exactly the same as its encoding 197 according to some transfer encoding option (e.g., the LDAP-specific 198 encoding might be defined to be the same as the BER encoding). 199 200 Transfer encoding options are mutually exclusive. An attribute 201 description SHALL NOT contain more than one transfer encoding option, 202 and SHALL NOT contain both a transfer encoding option and the binary 203 option. 204 205 Transfer encoding options are not tagging options [MODELS] so the 206 presence of a transfer encoding option does not specify an attribute 207 subtype. An attribute description containing a transfer encoding 208 option references exactly the same attribute as the same attribute 209 description without the transfer encoding option. The 210 supertype/subtype relationships of attributes with tagging options 211 are not altered in any way by the presence or absence of transfer 212 encoding options. 213 214 An attribute description SHALL be treated as unrecognized if it 215 contains a transfer encoding option and the syntax of the attribute 216 does not have an associated ASN.1 type [SYNTAX], or if the nominated 217 218 219 220Legg Expires 16 December 2004 [Page 4] 221 222INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 223 224 225 encoding is not supported for that type. 226 227 The presence or absence of a transfer encoding option only affects 228 the transfer of attribute and assertion values in protocol; servers 229 store any particular attribute value in a single format of their 230 choosing. 231 2324. Defined Transfer Encoding Options 233 234 The attribute option string "transfer-ber" specifies that the 235 associated attribute values or assertion value are (to be) encoded 236 according to the Basic Encoding Rules [X690] of ASN.1. This option 237 is similar to the binary option [BINARY], however servers are more 238 restricted in when they can use "transfer-ber" which leads to more 239 predictability in the results returned to clients who request 240 "transfer-ber". 241 242 The attribute option string "transfer-der" specifies that the 243 associated attribute values or assertion value are (to be) encoded 244 according to the Distinguished Encoding Rules [X690] of ASN.1. 245 246 The attribute option string "transfer-gser" specifies that the 247 associated attribute values or assertion value are (to be) encoded 248 according to the Generic String Encoding Rules (GSER) [RFC3641]. 249 250 The attribute option string "transfer-rxer" specifies that the 251 associated attribute values or assertion value are (to be) encoded as 252 an XML document [XML]. The [local name] of the [document element] of 253 the document information item representing the associated value SHALL 254 be the identifier of the NamedType [X680] in the LDAP ASN.1 255 specification [PROT] defining the associated attribute value or 256 assertion value, or "item" if the associated value isn't in a 257 NamedType. This means: 258 259 - for an AttributeValue the identifier is "value" in every case, 260 261 - for an AssertionValue in an AttributeValueAssertion the identifier 262 is "assertionValue", 263 264 - for an AssertionValue in a SubstringFilter the identifier is 265 "initial", "any" or "final", as appropriate, 266 267 - for an AssertionValue in a MatchingRuleAssertion the identifier is 268 "matchValue". 269 270 The [namespace name] of the [document element] SHALL have no value. 271 The content of the [document element] is the Robust XML Encoding 272 Rules (RXER) [RXER] encoding of the associated attribute or assertion 273 274 275 276Legg Expires 16 December 2004 [Page 5] 277 278INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 279 280 281 value. Note that the enclosing element for the RXER encoding has the 282 form it would take in an XLDAP operation [XLDAP]. 283 284 Note that, like all attribute options, the strings representing 285 transfer encoding options are case insensitive. 286 287 All future registrations of option strings for transfer encoding 288 options should use the "transfer-" prefix so that LDAP clients and 289 servers can recognize that an option is a transfer encoding option 290 even though the particular encoding rules may be unrecognized. 291 2925. Attributes Returned in a Search 293 294 An LDAP search request [PROT] contains a list of the attributes (the 295 requested attributes list) to be returned from each entry matching 296 the search filter. An attribute description in the requested 297 attributes list also implicitly requests all subtypes of the 298 attribute type in the attribute description, whether through 299 attribute subtyping or attribute tagging option subtyping [MODELS]. 300 301 The requested attributes list MAY contain attribute descriptions with 302 a transfer encoding option, but MUST NOT contain two attribute 303 descriptions with the same attribute type and the same tagging 304 options (even if only one of them has a transfer encoding option). A 305 transfer encoding option in an attribute description in the requested 306 attributes list implicitly applies to the subtypes of the attribute 307 type in the attribute description. 308 309 If the list of attributes in a search request is empty, or contains 310 the special attribute description string "*", then all user 311 attributes are requested to be returned. 312 313 In general, it is possible for a particular attribute to be 314 explicitly requested by an attribute description and/or implicitly 315 requested by the attribute descriptions of one or more of its 316 supertypes. In such cases the effective transfer encoding being 317 requested for a particular attribute is determined by the transfer 318 encoding option (or lack thereof) in the most specific attribute 319 description in the requested attributes list that applies to the 320 attribute. 321 322 An applicable attribute description with an actual attribute type is 323 more specific than the special attribute description string "*". 324 325 If the attribute type of one applicable attribute description is a 326 direct or indirect subtype of the attribute type in another 327 applicable attribute description then the former attribute 328 description is more specific than the latter attribute description. 329 330 331 332Legg Expires 16 December 2004 [Page 6] 333 334INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 335 336 337 If two applicable attribute descriptions have the same attribute type 338 and the tagging options of one attribute description are a superset 339 of the tagging options of the other attribute description then the 340 former attribute description is more specific than the latter 341 attribute description. 342 343 Attributes MUST either be returned in the effective transfer encoding 344 requested, be returned with no attribute values, or be omitted from 345 the results. An attribute SHALL NOT be returned using an encoding 346 other than the effective transfer encoding requested. 347 348 Regardless of the encoding chosen, a particular attribute value is 349 returned at most once. 350 3516. Syntaxes Requiring Binary Transfer 352 353 Certain syntaxes are required to be transferred in the BER encoded 354 form. These syntaxes are said to have a binary transfer requirement. 355 The Certificate, Certificate List, Certificate Pair and Supported 356 Algorithm syntaxes [PKI] are examples of syntaxes with a binary 357 transfer requirement. These syntaxes also have an additional 358 requirement that the exact BER encoding must be preserved. Note that 359 this is a property of the syntaxes themselves, and not a property of 360 the binary option or any of the transfer encoding options. 361 362 Transfer encoding options SHALL take precedence over the requirement 363 for binary transfer. For example, if the effective transfer encoding 364 requested is say "transfer-gser", then attribute values of a syntax 365 with a binary transfer requirement will be GSER encoded. In the 366 absence of a transfer encoding option the normal rules on binary 367 transfer and the use of the binary option SHALL apply. 368 3697. Security Considerations 370 371 There is a requirement on some attribute syntaxes that the exact BER 372 encoding of values of that syntax be preserved. In general, a 373 transformation from the BER encoding into some other encoding (e.g., 374 GSER) and back into the BER encoding will not necessarily reproduce 375 exactly the octets of the original BER encoding. 376 377 Applications needing the original BER encoding to be preserved, e.g., 378 for the verification of digital signatures, MUST NOT request 379 attributes with such a requirement using a transfer encoding option. 380 These attributes MUST be requested explicitly or implicitly with the 381 binary option, or implicitly without the binary option (or any 382 transfer encoding option). 383 384 When interpreting security-sensitive fields, and in particular fields 385 386 387 388Legg Expires 16 December 2004 [Page 7] 389 390INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 391 392 393 used to grant or deny access, implementations MUST ensure that any 394 matching rule comparisons are done on the underlying abstract value, 395 regardless of the particular encoding used. 396 3978. IANA Considerations 398 399 The Internet Assigned Numbers Authority (IANA) is requested to update 400 the LDAP attribute description option registry [BCP64] as indicated 401 by the following templates: 402 403 Subject: Request for 404 LDAP Attribute Description Option Registration 405 Option Name: transfer-ber 406 Family of Options: NO 407 Person & email address to contact for further information: 408 Steven Legg <steven.legg@adacel.com.au> 409 Specification: RFC XXXX 410 Author/Change Controller: IESG 411 Comments: 412 413 Subject: Request for 414 LDAP Attribute Description Option Registration 415 Option Name: transfer-der 416 Family of Options: NO 417 Person & email address to contact for further information: 418 Steven Legg <steven.legg@adacel.com.au> 419 Specification: RFC XXXX 420 Author/Change Controller: IESG 421 Comments: 422 423 Subject: Request for 424 LDAP Attribute Description Option Registration 425 Option Name: transfer-gser 426 Family of Options: NO 427 Person & email address to contact for further information: 428 Steven Legg <steven.legg@adacel.com.au> 429 Specification: RFC XXXX 430 Author/Change Controller: IESG 431 Comments: 432 433 Subject: Request for 434 LDAP Attribute Description Option Registration 435 Option Name: transfer-rxer 436 Family of Options: NO 437 Person & email address to contact for further information: 438 Steven Legg <steven.legg@adacel.com.au> 439 Specification: RFC XXXX 440 Author/Change Controller: IESG 441 442 443 444Legg Expires 16 December 2004 [Page 8] 445 446INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 447 448 449 Comments: 450 4519. References 452 4539.1. Normative References 454 455 [KEYWORD] Bradner, S., "Key words for use in RFCs to Indicate 456 Requirement Levels", BCP 14, RFC 2119, March 1997. 457 458 [BCP64] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 459 Considerations for the Lightweight Directory Access 460 Protcol (LDAP)", BCP 64, RFC 3383, September 2002. 461 462 [ROADMAP] Zeilenga, K., "Lightweight Directory Access Protocol 463 (LDAP): Technical Specification Road Map", 464 draft-ietf-ldapbis-roadmap-xx.txt, a work in progress, 465 June 2004. 466 467 [MODELS] Zeilenga, K., "LDAP: Directory Information Models", 468 draft-ietf-ldapbis-models-xx.txt, a work in progress, June 469 2004. 470 471 [PROT] Sermersheim, J., "LDAP: The Protocol", 472 draft-ietf-ldapbis-protocol-xx.txt, a work in progress, 473 May 2004. 474 475 [SYNTAX] Legg, S. and K. Dally, "Lightweight Directory Access 476 Protocol (LDAP): Syntaxes and Matching Rules", 477 draft-ietf-ldapbis-syntaxes-xx.txt, a work in progress, 478 May 2004. 479 480 [RFC3641] Legg, S., "Generic String Encoding Rules (GSER) for ASN.1 481 Types", RFC 3641, October 2003. 482 483 [BINARY] Legg, S., "Lightweight Directory Access Protocol (LDAP): 484 The Binary Encoding Option", 485 draft-legg-ldap-binary-xx.txt, a work in progress, June 486 2004. 487 488 [RXER] Legg, S. and D. Prager, "Robust XML Encoding Rules for 489 ASN.1 Types", draft-legg-xed-rxer-00.txt, a work in 490 progress, June 2004. 491 492 [X680] ITU-T Recommendation X.680 (07/02) | ISO/IEC 8824-1, 493 Information technology - Abstract Syntax Notation One 494 (ASN.1): Specification of basic notation. 495 496 [X690] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1, 497 498 499 500Legg Expires 16 December 2004 [Page 9] 501 502INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 503 504 505 Information Technology - ASN.1 encoding rules: 506 Specification of Basic Encoding Rules (BER), Canonical 507 Encoding Rules (CER) and Distinguished Encoding Rules 508 (DER). 509 510 [XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E. and 511 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third 512 Edition)", W3C Recommendation, 513 http://www.w3.org/TR/2004/REC-xml-20040204, February 2004. 514 515 [ISET] Cowan, J. and R. Tobin, "XML Information Set", 516 http://www.w3.org/TR/2001/REC-xml-infoset-20011024, 517 October 2001. 518 5199.2. Informative References 520 521 [XLDAP] Legg, S. and D. Prager, "The XML Enabled Directory: 522 Protocols", draft-legg-xed-protocols-xx.txt, a work in 523 progress, May 2004. 524 525Author's Address 526 527 Steven Legg 528 Adacel Technologies Ltd. 529 250 Bay Street 530 Brighton, Victoria 3186 531 AUSTRALIA 532 533 Phone: +61 3 8530 7710 534 Fax: +61 3 8530 7888 535 Email: steven.legg@adacel.com.au 536 537Full Copyright Statement 538 539 Copyright (C) The Internet Society (2004). This document is subject 540 to the rights, licenses and restrictions contained in BCP 78, and 541 except as set forth therein, the authors retain all their rights. 542 543 This document and the information contained herein are provided on an 544 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 545 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 546 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 547 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 548 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 549 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 550 551Intellectual Property 552 553 554 555 556Legg Expires 16 December 2004 [Page 10] 557 558INTERNET-DRAFT LDAP: Transfer Encoding Options June 16, 2004 559 560 561 The IETF takes no position regarding the validity or scope of any 562 Intellectual Property Rights or other rights that might be claimed to 563 pertain to the implementation or use of the technology described in 564 this document or the extent to which any license under such rights 565 might or might not be available; nor does it represent that it has 566 made any independent effort to identify any such rights. Information 567 on the procedures with respect to rights in RFC documents can be 568 found in BCP 78 and BCP 79. 569 570 Copies of IPR disclosures made to the IETF Secretariat and any 571 assurances of licenses to be made available, or the result of an 572 attempt made to obtain a general license or permission for the use of 573 such proprietary rights by implementers or users of this 574 specification can be obtained from the IETF on-line IPR repository at 575 http://www.ietf.org/ipr. 576 577 The IETF invites any interested party to bring to its attention any 578 copyrights, patents or patent applications, or other proprietary 579 rights that may cover technology that may be required to implement 580 this standard. Please address the information to the IETF at 581 ietf-ipr@ietf.org. 582 583Changes in Draft 01 584 585 A transfer encoding option for RXER has been added. 586 587Changes in Draft 02 588 589 The local name of the root element of the XML document representing 590 an attribute value encoded according to the transfer-rxer encoding 591 option has been changed from "item" to "value" to align with 592 revisions to the LDAP protocol specification [PROT]. 593 594 The Directory XML Encoding Rules (DXER) have been renamed to the 595 Robust XML Encoding Rules (RXER). 596 597Changes in Draft 03 598 599 The special attribute description strings that consist of the 600 asterisk character followed by a transfer encoding option, e.g., 601 "*;transfer-ber", "*;transfer-gser", have been removed from this 602 specification. An LDAP control will be defined in a separate 603 document to provide equivalent functionality. 604 605 606 607 608 609 610 611 612Legg Expires 16 December 2004 [Page 11] 613 614 615