-
Notifications
You must be signed in to change notification settings - Fork 0
/
rfc4511.txt
3811 lines (2573 loc) · 147 KB
/
rfc4511.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
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
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
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
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group J. Sermersheim, Ed.
Request for Comments: 4511 Novell, Inc.
Obsoletes: 2251, 2830, 3771 June 2006
Category: Standards Track
Lightweight Directory Access Protocol (LDAP): The Protocol
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document describes the protocol elements, along with their
semantics and encodings, of the Lightweight Directory Access Protocol
(LDAP). LDAP provides access to distributed directory services that
act in accordance with X.500 data and service models. These protocol
elements are based on those described in the X.500 Directory Access
Protocol (DAP).
Table of Contents
1. Introduction ....................................................3
1.1. Relationship to Other LDAP Specifications ..................3
2. Conventions .....................................................3
3. Protocol Model ..................................................4
3.1. Operation and LDAP Message Layer Relationship ..............5
4. Elements of Protocol ............................................5
4.1. Common Elements ............................................5
4.1.1. Message Envelope ....................................6
4.1.2. String Types ........................................7
4.1.3. Distinguished Name and Relative Distinguished Name ..8
4.1.4. Attribute Descriptions ..............................8
4.1.5. Attribute Value .....................................8
4.1.6. Attribute Value Assertion ...........................9
4.1.7. Attribute and PartialAttribute ......................9
4.1.8. Matching Rule Identifier ...........................10
4.1.9. Result Message .....................................10
4.1.10. Referral ..........................................12
Sermersheim Standards Track [Page 1]
RFC 4511 LDAPv3 June 2006
4.1.11. Controls ..........................................14
4.2. Bind Operation ............................................16
4.2.1. Processing of the Bind Request .....................17
4.2.2. Bind Response ......................................18
4.3. Unbind Operation ..........................................18
4.4. Unsolicited Notification ..................................19
4.4.1. Notice of Disconnection ............................19
4.5. Search Operation ..........................................20
4.5.1. Search Request .....................................20
4.5.2. Search Result ......................................27
4.5.3. Continuation References in the Search Result .......28
4.6. Modify Operation ..........................................31
4.7. Add Operation .............................................33
4.8. Delete Operation ..........................................34
4.9. Modify DN Operation .......................................34
4.10. Compare Operation ........................................36
4.11. Abandon Operation ........................................36
4.12. Extended Operation .......................................37
4.13. IntermediateResponse Message .............................39
4.13.1. Usage with LDAP ExtendedRequest and
ExtendedResponse ..................................40
4.13.2. Usage with LDAP Request Controls ..................40
4.14. StartTLS Operation .......................................40
4.14.1. StartTLS Request ..................................40
4.14.2. StartTLS Response .................................41
4.14.3. Removal of the TLS Layer ..........................41
5. Protocol Encoding, Connection, and Transfer ....................42
5.1. Protocol Encoding .........................................42
5.2. Transmission Control Protocol (TCP) .......................43
5.3. Termination of the LDAP session ...........................43
6. Security Considerations ........................................43
7. Acknowledgements ...............................................45
8. Normative References ...........................................46
9. Informative References .........................................48
10. IANA Considerations ...........................................48
Appendix A. LDAP Result Codes .....................................49
A.1. Non-Error Result Codes ....................................49
A.2. Result Codes ..............................................49
Appendix B. Complete ASN.1 Definition .............................54
Appendix C. Changes ...............................................60
C.1. Changes Made to RFC 2251 ..................................60
C.2. Changes Made to RFC 2830 ..................................66
C.3. Changes Made to RFC 3771 ..................................66
Sermersheim Standards Track [Page 2]
RFC 4511 LDAPv3 June 2006
1. Introduction
The Directory is "a collection of open systems cooperating to provide
directory services" [X.500]. A directory user, which may be a human
or other entity, accesses the Directory through a client (or
Directory User Agent (DUA)). The client, on behalf of the directory
user, interacts with one or more servers (or Directory System Agents
(DSA)). Clients interact with servers using a directory access
protocol.
This document details the protocol elements of the Lightweight
Directory Access Protocol (LDAP), along with their semantics.
Following the description of protocol elements, it describes the way
in which the protocol elements are encoded and transferred.
1.1. Relationship to Other LDAP Specifications
This document is an integral part of the LDAP Technical Specification
[RFC4510], which obsoletes the previously defined LDAP technical
specification, RFC 3377, in its entirety.
This document, together with [RFC4510], [RFC4513], and [RFC4512],
obsoletes RFC 2251 in its entirety. Section 3.3 is obsoleted by
[RFC4510]. Sections 4.2.1 (portions) and 4.2.2 are obsoleted by
[RFC4513]. Sections 3.2, 3.4, 4.1.3 (last paragraph), 4.1.4, 4.1.5,
4.1.5.1, 4.1.9 (last paragraph), 5.1, 6.1, and 6.2 (last paragraph)
are obsoleted by [RFC4512]. The remainder of RFC 2251 is obsoleted
by this document. Appendix C.1 summarizes substantive changes in the
remainder.
This document obsoletes RFC 2830, Sections 2 and 4. The remainder of
RFC 2830 is obsoleted by [RFC4513]. Appendix C.2 summarizes
substantive changes to the remaining sections.
This document also obsoletes RFC 3771 in entirety.
2. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
to be interpreted as described in [RFC2119].
Character names in this document use the notation for code points and
names from the Unicode Standard [Unicode]. For example, the letter
"a" may be represented as either <U+0061> or <LATIN SMALL LETTER A>.
Sermersheim Standards Track [Page 3]
RFC 4511 LDAPv3 June 2006
Note: a glossary of terms used in Unicode can be found in [Glossary].
Information on the Unicode character encoding model can be found in
[CharModel].
The term "transport connection" refers to the underlying transport
services used to carry the protocol exchange, as well as associations
established by these services.
The term "TLS layer" refers to Transport Layer Security (TLS)
services used in providing security services, as well as associations
established by these services.
The term "SASL layer" refers to Simply Authentication and Security
Layer (SASL) services used in providing security services, as well as
associations established by these services.
The term "LDAP message layer" refers to the LDAP Message Protocol
Data Unit (PDU) services used in providing directory services, as
well as associations established by these services.
The term "LDAP session" refers to combined services (transport
connection, TLS layer, SASL layer, LDAP message layer) and their
associations.
See the table in Section 5 for an illustration of these four terms.
3. Protocol Model
The general model adopted by this protocol is one of clients
performing protocol operations against servers. In this model, a
client transmits a protocol request describing the operation to be
performed to a server. The server is then responsible for performing
the necessary operation(s) in the Directory. Upon completion of an
operation, the server typically returns a response containing
appropriate data to the requesting client.
Protocol operations are generally independent of one another. Each
operation is processed as an atomic action, leaving the directory in
a consistent state.
Although servers are required to return responses whenever such
responses are defined in the protocol, there is no requirement for
synchronous behavior on the part of either clients or servers.
Requests and responses for multiple operations generally may be
exchanged between a client and server in any order. If required,
synchronous behavior may be controlled by client applications.
Sermersheim Standards Track [Page 4]
RFC 4511 LDAPv3 June 2006
The core protocol operations defined in this document can be mapped
to a subset of the X.500 (1993) Directory Abstract Service [X.511].
However, there is not a one-to-one mapping between LDAP operations
and X.500 Directory Access Protocol (DAP) operations. Server
implementations acting as a gateway to X.500 directories may need to
make multiple DAP requests to service a single LDAP request.
3.1. Operation and LDAP Message Layer Relationship
Protocol operations are exchanged at the LDAP message layer. When
the transport connection is closed, any uncompleted operations at the
LDAP message layer are abandoned (when possible) or are completed
without transmission of the response (when abandoning them is not
possible). Also, when the transport connection is closed, the client
MUST NOT assume that any uncompleted update operations have succeeded
or failed.
4. Elements of Protocol
The protocol is described using Abstract Syntax Notation One
([ASN.1]) and is transferred using a subset of ASN.1 Basic Encoding
Rules ([BER]). Section 5 specifies how the protocol elements are
encoded and transferred.
In order to support future extensions to this protocol, extensibility
is implied where it is allowed per ASN.1 (i.e., sequence, set,
choice, and enumerated types are extensible). In addition, ellipses
(...) have been supplied in ASN.1 types that are explicitly
extensible as discussed in [RFC4520]. Because of the implied
extensibility, clients and servers MUST (unless otherwise specified)
ignore trailing SEQUENCE components whose tags they do not recognize.
Changes to the protocol other than through the extension mechanisms
described here require a different version number. A client
indicates the version it is using as part of the BindRequest,
described in Section 4.2. If a client has not sent a Bind, the
server MUST assume the client is using version 3 or later.
Clients may attempt to determine the protocol versions a server
supports by reading the 'supportedLDAPVersion' attribute from the
root DSE (DSA-Specific Entry) [RFC4512].
4.1. Common Elements
This section describes the LDAPMessage envelope Protocol Data Unit
(PDU) format, as well as data type definitions, which are used in the
protocol operations.
Sermersheim Standards Track [Page 5]
RFC 4511 LDAPv3 June 2006
4.1.1. Message Envelope
For the purposes of protocol exchanges, all protocol operations are
encapsulated in a common envelope, the LDAPMessage, which is defined
as follows:
LDAPMessage ::= SEQUENCE {
messageID MessageID,
protocolOp CHOICE {
bindRequest BindRequest,
bindResponse BindResponse,
unbindRequest UnbindRequest,
searchRequest SearchRequest,
searchResEntry SearchResultEntry,
searchResDone SearchResultDone,
searchResRef SearchResultReference,
modifyRequest ModifyRequest,
modifyResponse ModifyResponse,
addRequest AddRequest,
addResponse AddResponse,
delRequest DelRequest,
delResponse DelResponse,
modDNRequest ModifyDNRequest,
modDNResponse ModifyDNResponse,
compareRequest CompareRequest,
compareResponse CompareResponse,
abandonRequest AbandonRequest,
extendedReq ExtendedRequest,
extendedResp ExtendedResponse,
...,
intermediateResponse IntermediateResponse },
controls [0] Controls OPTIONAL }
MessageID ::= INTEGER (0 .. maxInt)
maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --
The ASN.1 type Controls is defined in Section 4.1.11.
The function of the LDAPMessage is to provide an envelope containing
common fields required in all protocol exchanges. At this time, the
only common fields are the messageID and the controls.
If the server receives an LDAPMessage from the client in which the
LDAPMessage SEQUENCE tag cannot be recognized, the messageID cannot
be parsed, the tag of the protocolOp is not recognized as a request,
or the encoding structures or lengths of data fields are found to be
incorrect, then the server SHOULD return the Notice of Disconnection
Sermersheim Standards Track [Page 6]
RFC 4511 LDAPv3 June 2006
described in Section 4.4.1, with the resultCode set to protocolError,
and MUST immediately terminate the LDAP session as described in
Section 5.3.
In other cases where the client or server cannot parse an LDAP PDU,
it SHOULD abruptly terminate the LDAP session (Section 5.3) where
further communication (including providing notice) would be
pernicious. Otherwise, server implementations MUST return an
appropriate response to the request, with the resultCode set to
protocolError.
4.1.1.1. MessageID
All LDAPMessage envelopes encapsulating responses contain the
messageID value of the corresponding request LDAPMessage.
The messageID of a request MUST have a non-zero value different from
the messageID of any other request in progress in the same LDAP
session. The zero value is reserved for the unsolicited notification
message.
Typical clients increment a counter for each request.
A client MUST NOT send a request with the same messageID as an
earlier request in the same LDAP session unless it can be determined
that the server is no longer servicing the earlier request (e.g.,
after the final response is received, or a subsequent Bind
completes). Otherwise, the behavior is undefined. For this purpose,
note that Abandon and successfully abandoned operations do not send
responses.
4.1.2. String Types
The LDAPString is a notational convenience to indicate that, although
strings of LDAPString type encode as ASN.1 OCTET STRING types, the
[ISO10646] character set (a superset of [Unicode]) is used, encoded
following the UTF-8 [RFC3629] algorithm. Note that Unicode
characters U+0000 through U+007F are the same as ASCII 0 through 127,
respectively, and have the same single octet UTF-8 encoding. Other
Unicode characters have a multiple octet UTF-8 encoding.
LDAPString ::= OCTET STRING -- UTF-8 encoded,
-- [ISO10646] characters
The LDAPOID is a notational convenience to indicate that the
permitted value of this string is a (UTF-8 encoded) dotted-decimal
representation of an OBJECT IDENTIFIER. Although an LDAPOID is
Sermersheim Standards Track [Page 7]
RFC 4511 LDAPv3 June 2006
encoded as an OCTET STRING, values are limited to the definition of
<numericoid> given in Section 1.4 of [RFC4512].
LDAPOID ::= OCTET STRING -- Constrained to <numericoid>
-- [RFC4512]
For example,
1.3.6.1.4.1.1466.1.2.3
4.1.3. Distinguished Name and Relative Distinguished Name
An LDAPDN is defined to be the representation of a Distinguished Name
(DN) after encoding according to the specification in [RFC4514].
LDAPDN ::= LDAPString
-- Constrained to <distinguishedName> [RFC4514]
A RelativeLDAPDN is defined to be the representation of a Relative
Distinguished Name (RDN) after encoding according to the
specification in [RFC4514].
RelativeLDAPDN ::= LDAPString
-- Constrained to <name-component> [RFC4514]
4.1.4. Attribute Descriptions
The definition and encoding rules for attribute descriptions are
defined in Section 2.5 of [RFC4512]. Briefly, an attribute
description is an attribute type and zero or more options.
AttributeDescription ::= LDAPString
-- Constrained to <attributedescription>
-- [RFC4512]
4.1.5. Attribute Value
A field of type AttributeValue is an OCTET STRING containing an
encoded attribute value. The attribute value is encoded according to
the LDAP-specific encoding definition of its corresponding syntax.
The LDAP-specific encoding definitions for different syntaxes and
attribute types may be found in other documents and in particular
[RFC4517].
AttributeValue ::= OCTET STRING
Sermersheim Standards Track [Page 8]
RFC 4511 LDAPv3 June 2006
Note that there is no defined limit on the size of this encoding;
thus, protocol values may include multi-megabyte attribute values
(e.g., photographs).
Attribute values may be defined that have arbitrary and non-printable
syntax. Implementations MUST NOT display or attempt to decode an
attribute value if its syntax is not known. The implementation may
attempt to discover the subschema of the source entry and to retrieve
the descriptions of 'attributeTypes' from it [RFC4512].
Clients MUST only send attribute values in a request that are valid
according to the syntax defined for the attributes.
4.1.6. Attribute Value Assertion
The AttributeValueAssertion (AVA) type definition is similar to the
one in the X.500 Directory standards. It contains an attribute
description and a matching rule ([RFC4512], Section 4.1.3) assertion
value suitable for that type. Elements of this type are typically
used to assert that the value in assertionValue matches a value of an
attribute.
AttributeValueAssertion ::= SEQUENCE {
attributeDesc AttributeDescription,
assertionValue AssertionValue }
AssertionValue ::= OCTET STRING
The syntax of the AssertionValue depends on the context of the LDAP
operation being performed. For example, the syntax of the EQUALITY
matching rule for an attribute is used when performing a Compare
operation. Often this is the same syntax used for values of the
attribute type, but in some cases the assertion syntax differs from
the value syntax. See objectIdentiferFirstComponentMatch in
[RFC4517] for an example.
4.1.7. Attribute and PartialAttribute
Attributes and partial attributes consist of an attribute description
and attribute values. A PartialAttribute allows zero values, while
Attribute requires at least one value.
PartialAttribute ::= SEQUENCE {
type AttributeDescription,
vals SET OF value AttributeValue }
Sermersheim Standards Track [Page 9]
RFC 4511 LDAPv3 June 2006
Attribute ::= PartialAttribute(WITH COMPONENTS {
...,
vals (SIZE(1..MAX))})
No two of the attribute values may be equivalent as described by
Section 2.2 of [RFC4512]. The set of attribute values is unordered.
Implementations MUST NOT rely upon the ordering being repeatable.
4.1.8. Matching Rule Identifier
Matching rules are defined in Section 4.1.3 of [RFC4512]. A matching
rule is identified in the protocol by the printable representation of
either its <numericoid> or one of its short name descriptors
[RFC4512], e.g., 'caseIgnoreMatch' or '2.5.13.2'.
MatchingRuleId ::= LDAPString
4.1.9. Result Message
The LDAPResult is the construct used in this protocol to return
success or failure indications from servers to clients. To various
requests, servers will return responses containing the elements found
in LDAPResult to indicate the final status of the protocol operation
request.
LDAPResult ::= SEQUENCE {
resultCode ENUMERATED {
success (0),
operationsError (1),
protocolError (2),
timeLimitExceeded (3),
sizeLimitExceeded (4),
compareFalse (5),
compareTrue (6),
authMethodNotSupported (7),
strongerAuthRequired (8),
-- 9 reserved --
referral (10),
adminLimitExceeded (11),
unavailableCriticalExtension (12),
confidentialityRequired (13),
saslBindInProgress (14),
noSuchAttribute (16),
undefinedAttributeType (17),
inappropriateMatching (18),
constraintViolation (19),
attributeOrValueExists (20),
invalidAttributeSyntax (21),
Sermersheim Standards Track [Page 10]
RFC 4511 LDAPv3 June 2006
-- 22-31 unused --
noSuchObject (32),
aliasProblem (33),
invalidDNSyntax (34),
-- 35 reserved for undefined isLeaf --
aliasDereferencingProblem (36),
-- 37-47 unused --
inappropriateAuthentication (48),
invalidCredentials (49),
insufficientAccessRights (50),
busy (51),
unavailable (52),
unwillingToPerform (53),
loopDetect (54),
-- 55-63 unused --
namingViolation (64),
objectClassViolation (65),
notAllowedOnNonLeaf (66),
notAllowedOnRDN (67),
entryAlreadyExists (68),
objectClassModsProhibited (69),
-- 70 reserved for CLDAP --
affectsMultipleDSAs (71),
-- 72-79 unused --
other (80),
... },
matchedDN LDAPDN,
diagnosticMessage LDAPString,
referral [3] Referral OPTIONAL }
The resultCode enumeration is extensible as defined in Section 3.8 of
[RFC4520]. The meanings of the listed result codes are given in
Appendix A. If a server detects multiple errors for an operation,
only one result code is returned. The server should return the
result code that best indicates the nature of the error encountered.
Servers may return substituted result codes to prevent unauthorized
disclosures.
The diagnosticMessage field of this construct may, at the server's
option, be used to return a string containing a textual, human-
readable diagnostic message (terminal control and page formatting
characters should be avoided). As this diagnostic message is not
standardized, implementations MUST NOT rely on the values returned.
Diagnostic messages typically supplement the resultCode with
additional information. If the server chooses not to return a
textual diagnostic, the diagnosticMessage field MUST be empty.
Sermersheim Standards Track [Page 11]
RFC 4511 LDAPv3 June 2006
For certain result codes (typically, but not restricted to
noSuchObject, aliasProblem, invalidDNSyntax, and
aliasDereferencingProblem), the matchedDN field is set (subject to
access controls) to the name of the last entry (object or alias) used
in finding the target (or base) object. This will be a truncated
form of the provided name or, if an alias was dereferenced while
attempting to locate the entry, of the resulting name. Otherwise,
the matchedDN field is empty.
4.1.10. Referral
The referral result code indicates that the contacted server cannot
or will not perform the operation and that one or more other servers
may be able to. Reasons for this include:
- The target entry of the request is not held locally, but the server
has knowledge of its possible existence elsewhere.
- The operation is restricted on this server -- perhaps due to a
read-only copy of an entry to be modified.
The referral field is present in an LDAPResult if the resultCode is
set to referral, and it is absent with all other result codes. It
contains one or more references to one or more servers or services
that may be accessed via LDAP or other protocols. Referrals can be
returned in response to any operation request (except Unbind and
Abandon, which do not have responses). At least one URI MUST be
present in the Referral.
During a Search operation, after the baseObject is located, and
entries are being evaluated, the referral is not returned. Instead,
continuation references, described in Section 4.5.3, are returned
when other servers would need to be contacted to complete the
operation.
Referral ::= SEQUENCE SIZE (1..MAX) OF uri URI
URI ::= LDAPString -- limited to characters permitted in
-- URIs
If the client wishes to progress the operation, it contacts one of
the supported services found in the referral. If multiple URIs are
present, the client assumes that any supported URI may be used to
progress the operation.
Clients that follow referrals MUST ensure that they do not loop
between servers. They MUST NOT repeatedly contact the same server
for the same request with the same parameters. Some clients use a
Sermersheim Standards Track [Page 12]
RFC 4511 LDAPv3 June 2006
counter that is incremented each time referral handling occurs for an
operation, and these kinds of clients MUST be able to handle at least
ten nested referrals while progressing the operation.
A URI for a server implementing LDAP and accessible via TCP/IP (v4 or
v6) [RFC793][RFC791] is written as an LDAP URL according to
[RFC4516].
Referral values that are LDAP URLs follow these rules:
- If an alias was dereferenced, the <dn> part of the LDAP URL MUST be
present, with the new target object name.
- It is RECOMMENDED that the <dn> part be present to avoid ambiguity.
- If the <dn> part is present, the client uses this name in its next
request to progress the operation, and if it is not present the
client uses the same name as in the original request.
- Some servers (e.g., participating in distributed indexing) may
provide a different filter in a URL of a referral for a Search
operation.
- If the <filter> part of the LDAP URL is present, the client uses
this filter in its next request to progress this Search, and if it
is not present the client uses the same filter as it used for that
Search.
- For Search, it is RECOMMENDED that the <scope> part be present to
avoid ambiguity.
- If the <scope> part is missing, the scope of the original Search is
used by the client to progress the operation.
- Other aspects of the new request may be the same as or different
from the request that generated the referral.
Other kinds of URIs may be returned. The syntax and semantics of
such URIs is left to future specifications. Clients may ignore URIs
that they do not support.
UTF-8 encoded characters appearing in the string representation of a
DN, search filter, or other fields of the referral value may not be
legal for URIs (e.g., spaces) and MUST be escaped using the % method
in [RFC3986].
Sermersheim Standards Track [Page 13]
RFC 4511 LDAPv3 June 2006
4.1.11. Controls
Controls provide a mechanism whereby the semantics and arguments of
existing LDAP operations may be extended. One or more controls may
be attached to a single LDAP message. A control only affects the
semantics of the message it is attached to.
Controls sent by clients are termed 'request controls', and those
sent by servers are termed 'response controls'.
Controls ::= SEQUENCE OF control Control
Control ::= SEQUENCE {
controlType LDAPOID,
criticality BOOLEAN DEFAULT FALSE,
controlValue OCTET STRING OPTIONAL }
The controlType field is the dotted-decimal representation of an
OBJECT IDENTIFIER that uniquely identifies the control. This
provides unambiguous naming of controls. Often, response control(s)
solicited by a request control share controlType values with the
request control.
The criticality field only has meaning in controls attached to
request messages (except UnbindRequest). For controls attached to
response messages and the UnbindRequest, the criticality field SHOULD
be FALSE, and MUST be ignored by the receiving protocol peer. A
value of TRUE indicates that it is unacceptable to perform the
operation without applying the semantics of the control.
Specifically, the criticality field is applied as follows:
- If the server does not recognize the control type, determines that
it is not appropriate for the operation, or is otherwise unwilling
to perform the operation with the control, and if the criticality
field is TRUE, the server MUST NOT perform the operation, and for
operations that have a response message, it MUST return with the
resultCode set to unavailableCriticalExtension.
- If the server does not recognize the control type, determines that
it is not appropriate for the operation, or is otherwise unwilling
to perform the operation with the control, and if the criticality
field is FALSE, the server MUST ignore the control.
- Regardless of criticality, if a control is applied to an
operation, it is applied consistently and impartially to the
entire operation.
Sermersheim Standards Track [Page 14]
RFC 4511 LDAPv3 June 2006
The controlValue may contain information associated with the
controlType. Its format is defined by the specification of the
control. Implementations MUST be prepared to handle arbitrary
contents of the controlValue octet string, including zero bytes. It
is absent only if there is no value information that is associated
with a control of its type. When a controlValue is defined in terms
of ASN.1, and BER-encoded according to Section 5.1, it also follows
the extensibility rules in Section 4.
Servers list the controlType of request controls they recognize in
the 'supportedControl' attribute in the root DSE (Section 5.1 of
[RFC4512]).
Controls SHOULD NOT be combined unless the semantics of the
combination has been specified. The semantics of control
combinations, if specified, are generally found in the control
specification most recently published. When a combination of
controls is encountered whose semantics are invalid, not specified
(or not known), the message is considered not well-formed; thus, the
operation fails with protocolError. Controls with a criticality of
FALSE may be ignored in order to arrive at a valid combination.
Additionally, unless order-dependent semantics are given in a
specification, the order of a combination of controls in the SEQUENCE
is ignored. Where the order is to be ignored but cannot be ignored
by the server, the message is considered not well-formed, and the
operation fails with protocolError. Again, controls with a
criticality of FALSE may be ignored in order to arrive at a valid
combination.
This document does not specify any controls. Controls may be
specified in other documents. Documents detailing control extensions
are to provide for each control:
- the OBJECT IDENTIFIER assigned to the control,
- direction as to what value the sender should provide for the
criticality field (note: the semantics of the criticality field are
defined above should not be altered by the control's
specification),
- whether the controlValue field is present, and if so, the format of
its contents,
- the semantics of the control, and
- optionally, semantics regarding the combination of the control with
other controls.
Sermersheim Standards Track [Page 15]
RFC 4511 LDAPv3 June 2006
4.2. Bind Operation
The function of the Bind operation is to allow authentication
information to be exchanged between the client and server. The Bind
operation should be thought of as the "authenticate" operation.
Operational, authentication, and security-related semantics of this
operation are given in [RFC4513].
The Bind request is defined as follows:
BindRequest ::= [APPLICATION 0] SEQUENCE {
version INTEGER (1 .. 127),
name LDAPDN,
authentication AuthenticationChoice }
AuthenticationChoice ::= CHOICE {
simple [0] OCTET STRING,
-- 1 and 2 reserved
sasl [3] SaslCredentials,
... }
SaslCredentials ::= SEQUENCE {
mechanism LDAPString,
credentials OCTET STRING OPTIONAL }
Fields of the BindRequest are:
- version: A version number indicating the version of the protocol to
be used at the LDAP message layer. This document describes version
3 of the protocol. There is no version negotiation. The client
sets this field to the version it desires. If the server does not
support the specified version, it MUST respond with a BindResponse
where the resultCode is set to protocolError.
- name: If not empty, the name of the Directory object that the
client wishes to bind as. This field may take on a null value (a
zero-length string) for the purposes of anonymous binds ([RFC4513],
Section 5.1) or when using SASL [RFC4422] authentication
([RFC4513], Section 5.2). Where the server attempts to locate the
named object, it SHALL NOT perform alias dereferencing.
- authentication: Information used in authentication. This type is
extensible as defined in Section 3.7 of [RFC4520]. Servers that do
not support a choice supplied by a client return a BindResponse
with the resultCode set to authMethodNotSupported.
Sermersheim Standards Track [Page 16]
RFC 4511 LDAPv3 June 2006
Textual passwords (consisting of a character sequence with a known
character set and encoding) transferred to the server using the
simple AuthenticationChoice SHALL be transferred as UTF-8 [RFC3629]
encoded [Unicode]. Prior to transfer, clients SHOULD prepare text
passwords as "query" strings by applying the SASLprep [RFC4013]
profile of the stringprep [RFC3454] algorithm. Passwords
consisting of other data (such as random octets) MUST NOT be
altered. The determination of whether a password is textual is a
local client matter.
4.2.1. Processing of the Bind Request
Before processing a BindRequest, all uncompleted operations MUST
either complete or be abandoned. The server may either wait for the
uncompleted operations to complete, or abandon them. The server then
proceeds to authenticate the client in either a single-step or
multi-step Bind process. Each step requires the server to return a
BindResponse to indicate the status of authentication.
After sending a BindRequest, clients MUST NOT send further LDAP PDUs
until receiving the BindResponse. Similarly, servers SHOULD NOT
process or respond to requests received while processing a
BindRequest.
If the client did not bind before sending a request and receives an
operationsError to that request, it may then send a BindRequest. If
this also fails or the client chooses not to bind on the existing
LDAP session, it may terminate the LDAP session, re-establish it, and
begin again by first sending a BindRequest. This will aid in
interoperating with servers implementing other versions of LDAP.
Clients may send multiple Bind requests to change the authentication
and/or security associations or to complete a multi-stage Bind
process. Authentication from earlier binds is subsequently ignored.
For some SASL authentication mechanisms, it may be necessary for the
client to invoke the BindRequest multiple times ([RFC4513], Section
5.2). Clients MUST NOT invoke operations between two Bind requests
made as part of a multi-stage Bind.
A client may abort a SASL bind negotiation by sending a BindRequest
with a different value in the mechanism field of SaslCredentials, or
an AuthenticationChoice other than sasl.
Sermersheim Standards Track [Page 17]
RFC 4511 LDAPv3 June 2006
If the client sends a BindRequest with the sasl mechanism field as an
empty string, the server MUST return a BindResponse with the
resultCode set to authMethodNotSupported. This will allow the client
to abort a negotiation if it wishes to try again with the same SASL
mechanism.
4.2.2. Bind Response
The Bind response is defined as follows.
BindResponse ::= [APPLICATION 1] SEQUENCE {
COMPONENTS OF LDAPResult,
serverSaslCreds [7] OCTET STRING OPTIONAL }
BindResponse consists simply of an indication from the server of the
status of the client's request for authentication.
A successful Bind operation is indicated by a BindResponse with a
resultCode set to success. Otherwise, an appropriate result code is
set in the BindResponse. For BindResponse, the protocolError result
code may be used to indicate that the version number supplied by the
client is unsupported.
If the client receives a BindResponse where the resultCode is set to
protocolError, it is to assume that the server does not support this
version of LDAP. While the client may be able proceed with another
version of this protocol (which may or may not require closing and
re-establishing the transport connection), how to proceed with
another version of this protocol is beyond the scope of this
document. Clients that are unable or unwilling to proceed SHOULD
terminate the LDAP session.
The serverSaslCreds field is used as part of a SASL-defined bind
mechanism to allow the client to authenticate the server to which it
is communicating, or to perform "challenge-response" authentication.
If the client bound with the simple choice, or the SASL mechanism
does not require the server to return information to the client, then
this field SHALL NOT be included in the BindResponse.
4.3. Unbind Operation
The function of the Unbind operation is to terminate an LDAP session.