RFC 4522

Lightweight Directory Access Protocol (LDAP): The Binary Encoding Option

📅 published June 2006, from ietf

RFC 4522 📜💖 Part 1 of 2

Okay bestie, here's the ID card 🪪✨ RFC 4522 is titled "Lightweight Directory Access Protocol (LDAP): The Binary Encoding Option" and it was written by Steven Legg at eB2Bcom 🎀. It's a Standards Track document in the Network Working Group, dated June 2006. The header doesn't list anything it obsoletes or updates, but the Introduction has some history on that, so keep reading 🧚

Status of This Memo 📜

This document specifies an Internet standards track protocol for the Internet community, and asks for discussion and suggestions for improvements. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🦋

Copyright (C) The Internet Society (2006) 🌸

Abstract 💌

Every attribute stored in an LDAP directory has a defined syntax, which is basically its data type 💅 A syntax definition tells you how attribute values that follow that syntax are normally represented when they get sent around in LDAP operations. That representation is called the LDAP-specific encoding, so it can be told apart from other ways of encoding attribute values 🧚

This document defines an attribute option called the binary option. When it's used, it says the associated attribute values are instead encoded using the Basic Encoding Rules (BER) that X.500 directories use 🫶

Table of Contents 📚

1. Introduction ....................................................2
2. Conventions .....................................................2
3. The Binary Option ...............................................2
4. Syntaxes Requiring Binary Transfer ..............................3
5. Attributes Returned in a Search .................................4
6. All User Attributes .............................................4
7. Conflicting Requests ............................................5
8. Security Considerations .........................................5
9. IANA Considerations .............................................5
10. References .....................................................5
   10.1. Normative References ......................................5
   10.2. Informative References ....................................6

1. Introduction ✨

Every attribute in an LDAP directory [RFC4510] has a defined syntax (i.e., data type), and that syntax controls the structure and format of its values 💖

The syntax description [RFC4517] says how attribute or assertion values [RFC4512] that follow the syntax are normally represented when they're transferred in LDAP operations [RFC4511]. This is the LDAP-specific encoding, named that way to tell it apart from other encoding methods 🌈

This document defines an attribute option, the binary option. You can put it in an attribute description [RFC4512] in an LDAP operation to say that the associated attribute values or assertion values are, or are being requested to be, encoded using the Basic Encoding Rules (BER) [BER] that X.500 [X.500] directories use, instead of the usual LDAP-specific encoding 🦋

Here's the history tea ☕ The binary option was first defined in RFC 2251 [RFC2251]. The LDAP technical specification [RFC4510] obsoleted the earlier LDAP technical specification [RFC3377], which included RFC 2251. The binary option didn't make it into the revised LDAP technical specification, for a bunch of reasons including implementation inconsistencies. This document doesn't try to fix those known inconsistencies 🙈

What this document does do is bring back the binary option for certain attribute syntaxes that specifically need it, like the certificate syntax [RFC4523]. It doesn't address using the binary option with attributes whose syntaxes don't require it. Unless a future specification covers that, this use is to be avoided 💅

2. Conventions 🎀

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119 [BCP14] 🫶

3. The Binary Option 🧚

The binary option is indicated by the attribute option string binary in an attribute description. Like all attribute options, the string for the binary option is case insensitive, so binary, BINARY and any other casing mean the same thing 💜

When the binary option is present in an attribute description, the associated attribute values or assertion values MUST be BER encoded. Otherwise, the values are encoded according to the LDAP-specific encoding [RFC4517] for the attribute's syntax. It's possible for a syntax to be defined so that its LDAP-specific encoding is exactly the same as its BER encoding, which is a fun little plot twist 🌸

In terms of the protocol [RFC4511], the binary option says that the contents octets of the associated AttributeValue or AssertionValue OCTET STRING are a complete BER encoding of the relevant value 🍓

The binary option is not a tagging option [RFC4512], so having it doesn't specify an attribute subtype. An attribute description with the binary option references exactly the same attribute as the one without it. The supertype/subtype relationships of attributes with tagging options aren't changed in any way by whether the binary option is there or not 🦋

An attribute description SHALL be treated as unrecognized if it contains the binary option and either the syntax of the attribute doesn't have an associated ASN.1 type [RFC4517], or the BER encoding of values of that type isn't supported 🙅‍♀️

The binary option only affects how attribute and assertion values are transferred in the protocol. Servers can store any particular attribute value in whatever format they like 👑

4. Syntaxes Requiring Binary Transfer 💎

Some attribute syntaxes are defined without an LDAP-specific encoding, so their attribute values have to be transferred in the BER-encoded form. For this document, these syntaxes are said to have a binary transfer requirement 🔥

The certificate, certificate list, certificate pair, and supported algorithm syntaxes [RFC4523] are examples of syntaxes with a binary transfer requirement. These syntaxes also have an extra requirement that the exact BER encoding must be preserved. This is a property of the syntaxes themselves, not a property of the binary option. Without this requirement, LDAP clients would need to re-encode values using the Distinguished Encoding Rules (DER) 🥹

An LDAP search request [RFC4511] contains a list of attributes, called the requested attributes list, that should be returned from each entry matching the search filter. An attribute description in the requested attributes list also implicitly asks for all subtypes of the attribute type in that attribute description, whether they come from attribute subtyping or from attribute tagging option subtyping [RFC4512] ✨

The requested attributes list MAY contain attribute descriptions with the binary option. It MUST NOT contain two attribute descriptions with the same attribute type and the same tagging options, even if only one of them has the binary option. The binary option in an attribute description in the requested attributes list implicitly applies to all the subtypes of the attribute type in that attribute description (however, see Section 7) 💅

Attributes of a syntax with the binary transfer requirement, if returned, SHALL be returned in the binary form. That means the binary option is in the attribute description and the associated attribute values are BER encoded. This happens regardless of whether the binary option was in the request, either for the attribute itself or for one of its supertypes 🫶

Attributes of a syntax without the binary transfer requirement, if returned, SHOULD be returned in the form that was explicitly requested. So if the attribute description in the requested attributes list has the binary option, the matching attribute in the result SHOULD be in the binary form. If the attribute description in the request doesn't have the binary option, the matching attribute in the result SHOULD NOT be in the binary form. A server MAY omit an attribute from the result if it doesn't support the requested encoding 🙈

However the encoding is chosen, a particular attribute value is returned at most once 💖

10.1. Normative References

okay bestie, these are the docs the whole spec leans on, so they're the ones you have to have read 📚✨

  • [BCP14] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [BCP64] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006.
  • [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC RFC 4510, June 2006.
  • [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006.
  • [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006.
  • [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006.
  • [RFC4523] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) Schema Definitions for X.509 Certificates", RFC 4523, June 2006.
  • [BER] ITU-T Recommendation X.690 (07/02) | ISO/IEC 8825-1, Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER).

10.2. Informative References

these ones are the background reading 🌸 good to know, not strictly required to build the thing

  • [RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997.
  • [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access Protocol (v3): Technical Specification", RFC 3377, September 2002.
  • [X.500] ITU-T Recommendation X.500 (02/01) | ISO/IEC 9594-1:2001, Information technology - Open Systems Interconnection - The Directory: Overview of concepts, models and services

Author's Address 🎀

this is who wrote it, with the contact deets exactly as they appear 💌

Dr. Steven Legg
eB2Bcom
Suite 3, Woodhouse Corporate Centre
935 Station Street
Box Hill North, Victoria 3129
AUSTRALIA

Phone: +61 3 9896 7830
Fax:   +61 3 9896 7801
EMail: steven.legg@eb2bcom.com

okay, the legal stuff, but it's important so I'm keeping it word for word 🙈

Copyright (C) The Internet Society (2006).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property 🦋

the IETF is basically saying "we're not picking a side on patents or licensing here, and here's where to look if you want the details" 👀 so:

  • they don't take a position on whether any IPR claimed on this tech is valid or how far it reaches, and they're not saying licenses are or aren't available either. they also haven't done their own search for IPR 🙃
  • the procedures for rights in RFC documents are in BCP 78 and BCP 79.
  • IPR disclosures sent to the IETF Secretariat, any licence assurances, and the results of attempts to get a general licence or permission for implementers or users are all available from the IETF's online IPR repository at http://www.ietf.org/ipr.
  • if you know about any copyrights, patents, patent applications or other proprietary rights that might cover tech needed to implement this standard, tell the IETF at ietf-ipr@ietf.org 🫶

Acknowledgement 🌈

Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). 💜

📦 where this page comes from