git.sur5r.net Git - openldap/blob - doc/rfc/rfc4522.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                            S. Legg
   8 Request for Comments: 4522                                       eB2Bcom
   9 Category: Standards Track                                      June 2006
  10
  11
  12              Lightweight Directory Access Protocol (LDAP):
  13                        The Binary Encoding Option
  14
  15 Status of This Memo
  16
  17    This document specifies an Internet standards track protocol for the
  18    Internet community, and requests discussion and suggestions for
  19    improvements.  Please refer to the current edition of the "Internet
  20    Official Protocol Standards" (STD 1) for the standardization state
  21    and status of this protocol.  Distribution of this memo is unlimited.
  22
  23 Copyright Notice
  24
  25    Copyright (C) The Internet Society (2006).
  26
  27 Abstract
  28
  29    Each attribute stored in a Lightweight Directory Access Protocol
  30    (LDAP) directory has a defined syntax (i.e., data type).  A syntax
  31    definition specifies how attribute values conforming to the syntax
  32    are normally represented when transferred in LDAP operations.  This
  33    representation is referred to as the LDAP-specific encoding to
  34    distinguish it from other methods of encoding attribute values.  This
  35    document defines an attribute option, the binary option, that can be
  36    used to specify that the associated attribute values are instead
  37    encoded according to the Basic Encoding Rules (BER) used by X.500
  38    directories.
  39
  40 Table of Contents
  41
  42    1. Introduction ....................................................2
  43    2. Conventions .....................................................2
  44    3. The Binary Option ...............................................2
  45    4. Syntaxes Requiring Binary Transfer ..............................3
  46    5. Attributes Returned in a Search .................................4
  47    6. All User Attributes .............................................4
  48    7. Conflicting Requests ............................................5
  49    8. Security Considerations .........................................5
  50    9. IANA Considerations .............................................5
  51    10. References .....................................................5
  52       10.1. Normative References ......................................5
  53       10.2. Informative References ....................................6
  54
  55
  56
  57
  58 Legg                        Standards Track                     [Page 1]
  59 \f
  60 RFC 4522            LDAP: The Binary Encoding Option           June 2006
  61
  62
  63 1.  Introduction
  64
  65    Each attribute stored in a Lightweight Directory Access Protocol
  66    (LDAP) directory [RFC4510] has a defined syntax (i.e., data type)
  67    which constrains the structure and format of its values.
  68
  69    The description of each syntax [RFC4517] specifies how attribute or
  70    assertion values [RFC4512] conforming to the syntax are normally
  71    represented when transferred in LDAP operations [RFC4511].  This
  72    representation is referred to as the LDAP-specific encoding to
  73    distinguish it from other methods of encoding attribute values.
  74
  75    This document defines an attribute option, the binary option, which
  76    can be used in an attribute description [RFC4512] in an LDAP
  77    operation to specify that the associated attribute values or
  78    assertion values are, or are requested to be, encoded according to
  79    the Basic Encoding Rules (BER) [BER] as used by X.500 [X.500]
  80    directories, instead of the usual LDAP-specific encoding.
  81
  82    The binary option was originally defined in RFC 2251 [RFC2251].  The
  83    LDAP technical specification [RFC4510] has obsoleted the previously
  84    defined LDAP technical specification [RFC3377], which included RFC
  85    2251.  The binary option was not included in the revised LDAP
  86    technical specification for a variety of reasons including
  87    implementation inconsistencies.  No attempt is made here to resolve
  88    the known inconsistencies.
  89
  90    This document reintroduces the binary option for use with certain
  91    attribute syntaxes, such as certificate syntax [RFC4523], that
  92    specifically require it.  No attempt has been made to address use of
  93    the binary option with attributes of syntaxes that do not require its
  94    use.  Unless addressed in a future specification, this use is to be
  95    avoided.
  96
  97 2.  Conventions
  98
  99    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 100    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 101    document are to be interpreted as described in BCP 14, RFC 2119
 102    [BCP14].
 103
 104 3.  The Binary Option
 105
 106    The binary option is indicated with the attribute option string
 107    "binary" in an attribute description.  Note that, like all attribute
 108    options, the string representing the binary option is case
 109    insensitive.
 110
 111
 112
 113
 114 Legg                        Standards Track                     [Page 2]
 115 \f
 116 RFC 4522            LDAP: The Binary Encoding Option           June 2006
 117
 118
 119    Where the binary option is present in an attribute description, the
 120    associated attribute values or assertion values MUST be BER encoded
 121    (otherwise the values are encoded according to the LDAP-specific
 122    encoding [RFC4517] for the attribute's syntax).  Note that it is
 123    possible for a syntax to be defined such that its LDAP-specific
 124    encoding is exactly the same as its BER encoding.
 125
 126    In terms of the protocol [RFC4511], the binary option specifies that
 127    the contents octets of the associated AttributeValue or
 128    AssertionValue OCTET STRING are a complete BER encoding of the
 129    relevant value.
 130
 131    The binary option is not a tagging option [RFC4512], so the presence
 132    of the binary option does not specify an attribute subtype.  An
 133    attribute description containing the binary option references exactly
 134    the same attribute as the attribute description without the binary
 135    option.  The supertype/subtype relationships of attributes with
 136    tagging options are not altered in any way by the presence or absence
 137    of the binary option.
 138
 139    An attribute description SHALL be treated as unrecognized if it
 140    contains the binary option and the syntax of the attribute does not
 141    have an associated ASN.1 type [RFC4517], or the BER encoding of
 142    values of that type is not supported.
 143
 144    The presence or absence of the binary option only affects the
 145    transfer of attribute and assertion values in the protocol; servers
 146    store any particular attribute value in a format of their choosing.
 147
 148 4.  Syntaxes Requiring Binary Transfer
 149
 150    The attribute values of certain attribute syntaxes are defined
 151    without an LDAP-specific encoding and are required to be transferred
 152    in the BER-encoded form.  For the purposes of this document, these
 153    syntaxes are said to have a binary transfer requirement.  The
 154    certificate, certificate list, certificate pair, and supported
 155    algorithm syntaxes [RFC4523] are examples of syntaxes with a binary
 156    transfer requirement.  These syntaxes also have an additional
 157    requirement that the exact BER encoding must be preserved.  Note that
 158    this is a property of the syntaxes themselves, and not a property of
 159    the binary option.  In the absence of this requirement, LDAP clients
 160    would need to re-encode values using the Distinguished Encoding Rules
 161    (DER).
 162
 163
 164
 165
 166
 167
 168
 169
 170 Legg                        Standards Track                     [Page 3]
 171 \f
 172 RFC 4522            LDAP: The Binary Encoding Option           June 2006
 173
 174
 175 5.  Attributes Returned in a Search
 176
 177    An LDAP search request [RFC4511] contains a list of the attributes
 178    (the requested attributes list) to be returned from each entry
 179    matching the search filter.  An attribute description in the
 180    requested attributes list also implicitly requests all subtypes of
 181    the attribute type in the attribute description, whether through
 182    attribute subtyping or attribute tagging option subtyping [RFC4512].
 183
 184    The requested attributes list MAY contain attribute descriptions with
 185    the binary option, but MUST NOT contain two attribute descriptions
 186    with the same attribute type and the same tagging options (even if
 187    only one of them has the binary option).  The binary option in an
 188    attribute description in the requested attributes list implicitly
 189    applies to all the subtypes of the attribute type in the attribute
 190    description (however, see Section 7).
 191
 192    Attributes of a syntax with the binary transfer requirement, if
 193    returned, SHALL be returned in the binary form (i.e., with the binary
 194    option in the attribute description and the associated attribute
 195    values BER encoded) regardless of whether the binary option was
 196    present in the request (for the attribute or for one of its
 197    supertypes).
 198
 199    Attributes of a syntax without the binary transfer requirement, if
 200    returned, SHOULD be returned in the form explicitly requested.  That
 201    is, if the attribute description in the requested attributes list
 202    contains the binary option, then the corresponding attribute in the
 203    result SHOULD be in the binary form.  If the attribute description in
 204    the request does not contain the binary option, then the
 205    corresponding attribute in the result SHOULD NOT be in the binary
 206    form.  A server MAY omit an attribute from the result if it does not
 207    support the requested encoding.
 208
 209    Regardless of the encoding chosen, a particular attribute value is
 210    returned at most once.
 211
 212 6.  All User Attributes
 213
 214    If the list of attributes in a search request is empty or contains
 215    the special attribute description string "*", then all user
 216    attributes are requested to be returned.
 217
 218    Attributes of a syntax with the binary transfer requirement, if
 219    returned, SHALL be returned in the binary form.
 220
 221
 222
 223
 224
 225
 226 Legg                        Standards Track                     [Page 4]
 227 \f
 228 RFC 4522            LDAP: The Binary Encoding Option           June 2006
 229
 230
 231    Attributes of a syntax without the binary transfer requirement and
 232    having a defined LDAP-specific encoding SHOULD NOT be returned in the
 233    binary form.
 234
 235    Attributes of a syntax without the binary transfer requirement and
 236    without a defined LDAP-specific encoding may be returned in the
 237    binary form or omitted from the result.
 238
 239 7.  Conflicting Requests
 240
 241    A particular attribute could be explicitly requested by an attribute
 242    description and/or implicitly requested by the attribute descriptions
 243    of one or more of its supertypes, or by the special attribute
 244    description string "*".  If the binary option is present in at least
 245    one, but not all, of these attribute descriptions then the effect of
 246    the request with respect to binary transfer is implementation
 247    defined.
 248
 249 8.  Security Considerations
 250
 251    When interpreting security-sensitive fields, and in particular fields
 252    used to grant or deny access, implementations MUST ensure that any
 253    matching rule comparisons are done on the underlying abstract value,
 254    regardless of the particular encoding used.
 255
 256 9.  IANA Considerations
 257
 258    The Internet Assigned Numbers Authority (IANA) has updated the LDAP
 259    attribute description option registry [BCP64] as indicated by the
 260    following template:
 261
 262       Subject:
 263         Request for LDAP Attribute Description Option Registration
 264       Option Name: binary
 265       Family of Options: NO
 266       Person & email address to contact for further information:
 267         Steven Legg <steven.legg@eb2bcom.com>
 268       Specification: RFC 4522
 269       Author/Change Controller: IESG
 270
 271 10.  References
 272
 273 10.1.  Normative References
 274
 275    [BCP14]    Bradner, S., "Key words for use in RFCs to Indicate
 276               Requirement Levels", BCP 14, RFC 2119, March 1997.
 277
 278
 279
 280
 281
 282 Legg                        Standards Track                     [Page 5]
 283 \f
 284 RFC 4522            LDAP: The Binary Encoding Option           June 2006
 285
 286
 287    [BCP64]    Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
 288               Considerations for the Lightweight Directory Access
 289               Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
 290
 291    [RFC4510]  Zeilenga, K., Ed., "Lightweight Directory Access Protocol
 292               (LDAP): Technical Specification Road Map", RFC RFC 4510,
 293               June 2006.
 294
 295    [RFC4511]  Sermersheim, J., "Lightweight Directory Access Protocol
 296               (LDAP): The Protocol", RFC 4511, June 2006.
 297
 298    [RFC4512]  Zeilenga, K., "Lightweight Directory Access Protocol
 299               (LDAP): Directory Information Models", RFC 4512, June
 300               2006.
 301
 302    [RFC4517]  Legg, S., Ed., "Lightweight Directory Access Protocol
 303               (LDAP):  Syntaxes and Matching Rules", RFC 4517, June
 304               2006.
 305
 306    [RFC4523]  Zeilenga, K., "Lightweight Directory Access Protocol
 307               (LDAP) Schema Definitions for X.509 Certificates", RFC
 308               4523, June 2006.
 309
 310    [BER]      ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1,
 311               Information Technology - ASN.1 encoding rules:
 312               Specification of Basic Encoding Rules (BER), Canonical
 313               Encoding Rules (CER) and Distinguished Encoding Rules
 314               (DER).
 315
 316 10.2.  Informative References
 317
 318    [RFC2251]  Wahl, M., Howes, T., and S. Kille, "Lightweight Directory
 319               Access Protocol (v3)", RFC 2251, December 1997.
 320
 321    [RFC3377]  Hodges, J. and R. Morgan, "Lightweight Directory Access
 322               Protocol (v3): Technical Specification", RFC 3377,
 323               September 2002.
 324
 325    [X.500]    ITU-T Recommendation X.500 (02/01) | ISO/IEC 9594-1:2001,
 326               Information technology - Open Systems Interconnection -
 327               The Directory:  Overview of concepts, models and services
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338 Legg                        Standards Track                     [Page 6]
 339 \f
 340 RFC 4522            LDAP: The Binary Encoding Option           June 2006
 341
 342
 343 Author's Address
 344
 345    Dr. Steven Legg
 346    eB2Bcom
 347    Suite 3, Woodhouse Corporate Centre
 348    935 Station Street
 349    Box Hill North, Victoria 3129
 350    AUSTRALIA
 351
 352    Phone: +61 3 9896 7830
 353    Fax:   +61 3 9896 7801
 354    EMail: steven.legg@eb2bcom.com
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394 Legg                        Standards Track                     [Page 7]
 395 \f
 396 RFC 4522            LDAP: The Binary Encoding Option           June 2006
 397
 398
 399 Full Copyright Statement
 400
 401    Copyright (C) The Internet Society (2006).
 402
 403    This document is subject to the rights, licenses and restrictions
 404    contained in BCP 78, and except as set forth therein, the authors
 405    retain all their rights.
 406
 407    This document and the information contained herein are provided on an
 408    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
 409    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
 410    ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
 411    INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
 412    INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
 413    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 414
 415 Intellectual Property
 416
 417    The IETF takes no position regarding the validity or scope of any
 418    Intellectual Property Rights or other rights that might be claimed to
 419    pertain to the implementation or use of the technology described in
 420    this document or the extent to which any license under such rights
 421    might or might not be available; nor does it represent that it has
 422    made any independent effort to identify any such rights.  Information
 423    on the procedures with respect to rights in RFC documents can be
 424    found in BCP 78 and BCP 79.
 425
 426    Copies of IPR disclosures made to the IETF Secretariat and any
 427    assurances of licenses to be made available, or the result of an
 428    attempt made to obtain a general license or permission for the use of
 429    such proprietary rights by implementers or users of this
 430    specification can be obtained from the IETF on-line IPR repository at
 431    http://www.ietf.org/ipr.
 432
 433    The IETF invites any interested party to bring to its attention any
 434    copyrights, patents or patent applications, or other proprietary
 435    rights that may cover technology that may be required to implement
 436    this standard.  Please address the information to the IETF at
 437    ietf-ipr@ietf.org.
 438
 439 Acknowledgement
 440
 441    Funding for the RFC Editor function is provided by the IETF
 442    Administrative Support Activity (IASA).
 443
 444
 445
 446
 447
 448
 449
 450 Legg                        Standards Track                     [Page 8]
 451 \f