git.sur5r.net Git - openldap/blob - doc/drafts/draft-legg-ldap-transfer-xx.txt

   1 INTERNET-DRAFT                                                   S. Legg
   2 draft-legg-ldap-transfer-03.txt                      Adacel Technologies
   3 Intended Category: Standards Track                          16 June 2004
   4 Updates: 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
  45 Abstract
  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
  52 Legg                    Expires 16 December 2004                [Page 1]
  53 \f
  54 INTERNET-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
 108 Legg                    Expires 16 December 2004                [Page 2]
 109 \f
 110 INTERNET-DRAFT       LDAP: Transfer Encoding Options       June 16, 2004
 111
 112
 113 Table 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
 129 1.  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
 152 2.  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
 164 Legg                    Expires 16 December 2004                [Page 3]
 165 \f
 166 INTERNET-DRAFT       LDAP: Transfer Encoding Options       June 16, 2004
 167
 168
 169    are presented per the Infoset, e.g., [local name].
 170
 171 3.  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
 220 Legg                    Expires 16 December 2004                [Page 4]
 221 \f
 222 INTERNET-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
 232 4.  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
 276 Legg                    Expires 16 December 2004                [Page 5]
 277 \f
 278 INTERNET-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
 292 5.  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
 332 Legg                    Expires 16 December 2004                [Page 6]
 333 \f
 334 INTERNET-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
 351 6.  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
 369 7.  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
 388 Legg                    Expires 16 December 2004                [Page 7]
 389 \f
 390 INTERNET-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
 397 8.  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
 444 Legg                    Expires 16 December 2004                [Page 8]
 445 \f
 446 INTERNET-DRAFT       LDAP: Transfer Encoding Options       June 16, 2004
 447
 448
 449       Comments:
 450
 451 9.  References
 452
 453 9.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
 500 Legg                    Expires 16 December 2004                [Page 9]
 501 \f
 502 INTERNET-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
 519 9.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
 525 Author'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
 537 Full 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
 551 Intellectual Property
 552
 553
 554
 555
 556 Legg                    Expires 16 December 2004               [Page 10]
 557 \f
 558 INTERNET-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
 583 Changes in Draft 01
 584
 585    A transfer encoding option for RXER has been added.
 586
 587 Changes 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
 597 Changes 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
 612 Legg                    Expires 16 December 2004               [Page 11]
 613 \f
 614