mirror/openldap
2
0
Fork 0
mirror of https://git.openldap.org/openldap/openldap.git synced 2024-12-21 03:10:25 +08:00
Code Issues Packages Projects Releases Wiki Activity

latest dupent I-D

Browse Source
This commit is contained in:
Kurt Zeilenga 2002-09-17 21:05:41 +00:00
parent 3eb21d8a6c
commit 043e5c5a13
1 changed files with 519 additions and 528 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

297
doc/drafts/draft-ietf-ldapext-ldapv3-dupent-xx.txt
View File

@ -2,7 +2,7 @@
LDAPEXT Working Group J. Sermersheim LDAPEXT Working Group J. Sermersheim
Internet Draft Novell, Inc Internet Draft Novell, Inc
Document: draft-ietf-ldapext-ldapv3-dupent-06.txt October 2000 Document: draft-ietf-ldapext-ldapv3-dupent-08.txt Sept 2002
Intended Category: Standard Track Intended Category: Standard Track
@ -12,7 +12,7 @@ Intended Category: Standard Track
1. Status of this Memo 1. Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 [1]. all provisions of Section 10 of RFC2026 [1].
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
@ -34,35 +34,40 @@ Intended Category: Standard Track
This document describes a Duplicate Entry Representation control This document describes a Duplicate Entry Representation control
extension for the LDAP Search operation. By using the control with extension for the LDAP Search operation. By using the control with
an LDAP search, a client requests that the server return separate an LDAP search, a client requests that the server return separate
entries for each value held in the specified attributes. For entries for each value held in the specified attribute(s). For
instance, if a specified attribute of an entry holds multiple instance, if a specified attribute of an entry holds multiple
values, the search operation will return multiple instances of that values, the search operation will return multiple instances of that
entry, each instance holding a separate single value in that entry, each instance holding a separate single value in that
attribute. attribute.
3. Overview 3. Introduction
The Server-Side Sorting control [RFC2891] allows the server to order This document describes controls, which allow duplicate entries to
search result entries based on attribute values (sort keys). It be returned in the result set of search operation. Each duplicated
does not allow one to specify behavior when an attribute contains entry represents a distinct value (or combination of values) of the
multiple values. The default behavior, as outlined in 7.9 of set of specified multi-valued attributes.
[X.511], is to use the smallest value as the sort key.
An application may need to produce an ordered list of entries, For example, an application may need to produce an ordered list of
sorted by a multi-valued attribute, where each attribute value is entries, sorted by a multi-valued attribute, where each attribute
represented in the list. In order to do this, a separate control is value is represented in the list. The Server-Side Sorting control
[RFC2891] allows the server to order search result entries based on
attribute values (sort keys). But it does not allow one to specify
behavior when an attribute contains multiple values. The default
Sermersheim Internet-Draft - Expires Mar 2003 Page 1
LDAP Control for a Duplicate Entry Representation of Search Results
behavior, as outlined in 7.9 of [X.511], is to use the smallest
order value as the sort key.
In order to produce an ordered list, where each value of a multi-
valued attribute is sorted into the list, a separate control is
needed which causes the set of entries to be expanded sufficiently needed which causes the set of entries to be expanded sufficiently
to represent each attribute value prior to sorting. to represent each attribute value prior to sorting.
Sermersheim Internet-Draft - Expires Apr 2001 Page 1
LDAP Control for a Duplicate Entry Representation of Search Results
This document describes controls, which allow duplicate entries in
the result set of search, where each entry represents a distinct
value of a given multiple valued attribute.
An example of this would be a sorted list of all telephone numbers An example of this would be a sorted list of all telephone numbers
in an organization. Because any entry may have multiple telephone in an organization. Because any entry may have multiple telephone
@ -75,10 +80,15 @@ LDAP Control for a Duplicate Entry Representation of Search Results
to create a result set of duplicate groupOfNames entries, each with to create a result set of duplicate groupOfNames entries, each with
a single, unique value in its member attribute. a single, unique value in its member attribute.
4. Conventions
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
used in this document carry the meanings described in [RFC2119]. used in this document carry the meanings described in [RFC2119].
4. The Controls All controlValue data is represented as ASN.1 in this document, and
is to be BER encoded as stated in Section 5.1 of [RFC2251].
5. The Controls
Support for the controls is advertised by the presence of their OID Support for the controls is advertised by the presence of their OID
in the supportedControl attribute of a server's root DSE. The OID in the supportedControl attribute of a server's root DSE. The OID
@ -86,7 +96,7 @@ LDAP Control for a Duplicate Entry Representation of Search Results
OIDs for the response controls are "2.16.840.1.113719.1.27.101.2" OIDs for the response controls are "2.16.840.1.113719.1.27.101.2"
and "2.16.840.1.113719.1.27.101.3". and "2.16.840.1.113719.1.27.101.3".
4.1 Request Control 5.1 Request Control
This control is included in the searchRequest message as part of the This control is included in the searchRequest message as part of the
controls field of the LDAPMessage, as defined in Section 4.1.12 of controls field of the LDAPMessage, as defined in Section 4.1.12 of
@ -94,15 +104,19 @@ LDAP Control for a Duplicate Entry Representation of Search Results
The controlType is set to "2.16.840.1.113719.1.27.101.1". The The controlType is set to "2.16.840.1.113719.1.27.101.1". The
criticality MAY be set to either TRUE or FALSE. The controlValue is criticality MAY be set to either TRUE or FALSE. The controlValue is
an OCTET STRING, whose value is the BER encoding of the following defined as the following DuplicateEntryRequest:
type:
DuplicateEntryRequest ::= SEQUENCE { DuplicateEntryRequest ::= SEQUENCE {
AttributeDescriptionList, -- from [RFC2251] AttributeDescriptionList, -- from [RFC2251]
PartialApplicationAllowed BOOLEAN DEFAULT TRUE } PartialApplicationAllowed BOOLEAN DEFAULT TRUE }
4.1.1 AttributeDescriptionList Semantics 5.1.1 AttributeDescriptionList Semantics
Sermersheim Internet-Draft - Expires Mar 2003 Page 2
LDAP Control for a Duplicate Entry Representation of Search Results
The AttributeDescriptionList data type is described in 4.1.5 of The AttributeDescriptionList data type is described in 4.1.5 of
[RFC2251] and describes a list of zero or more AttributeDescription [RFC2251] and describes a list of zero or more AttributeDescription
@ -114,25 +128,29 @@ LDAP Control for a Duplicate Entry Representation of Search Results
AttributeDescription ::= LDAPString AttributeDescription ::= LDAPString
Sermersheim Internet-Draft - Expires Jan 2001 Page 2
LDAP Control for a Duplicate Entry Representation of Search Results
A value of AttributeDescription is based on the following BNF: A value of AttributeDescription is based on the following BNF:
attributeDescription = AttributeType [ ";" <options> ] attributeDescription = AttributeType [ ";" <options> ]
While processing a search request, a server implementation examines While processing a search request, a server implementation examines
this list. If a specified attribute or attribute subtype exists in this list. If a specified attribute or attribute subtype exists in
an entry to be returned by search, and that attribute holds multiple an entry to be returned by the search operation, and that attribute
values, the server treats the entry as if it were multiple, holds multiple values, the server treats the entry as if it were
duplicate entries -- the specified attributes each holding a single, multiple, duplicate entries -- the specified attributes each holding
unique value from the original set of values of that attribute. a single, unique value from the original set of values of that
attribute. Note that this may result in search result entries that
no longer match the search filter.
Client implementations SHOULD NOT specify attribute type options Specifying an attribute supertype has the effect of treating all
that indicate transfer encoding (e.g. ;binary). values of that attribute's subtypes as if they were values of the
specified attribute supertype. See Section 6.2 for an example of
this.
When attribute descriptions contain subtyping options, they are
treated in the same manner as is described in Section 4.1.5 of
[RFC2251]. Semantics are undefined if an attribute description
contains a non-subtyping option, and SHOULD NOT be specified by
clients.
When two or more attributes are specified by this control, the When two or more attributes are specified by this control, the
number of duplicate entries is the combination of all values in each number of duplicate entries is the combination of all values in each
@ -148,19 +166,24 @@ LDAP Control for a Duplicate Entry Representation of Search Results
If an attribute is unrecognized, that attribute is ignored when If an attribute is unrecognized, that attribute is ignored when
processing the control. processing the control.
4.1.2 PartialApplicationAllowed Semantics 5.1.2 PartialApplicationAllowed Semantics
The PartialApplicationAllowed field is used to specify whether the The PartialApplicationAllowed field is used to specify whether the
client will allow the server to apply this control to a subset of client will allow the server to apply this control to a subset of
Sermersheim Internet-Draft - Expires Mar 2003 Page 3
LDAP Control for a Duplicate Entry Representation of Search Results
the search result set. If TRUE, the server is free to arbitrarily the search result set. If TRUE, the server is free to arbitrarily
apply this control to no, any, or all search results. If FALSE, the apply this control to no, any, or all search results. If FALSE, the
server MUST either apply the control to all search results or fail server MUST either apply the control to all search results or fail
to support the control at all. to support the control at all.
Client implementations use the DuplicateSearchResult control to Client implementations use the DuplicateSearchResult control to
discover which search results have been affected by this control discover which search results have been affected by this control.
4.2 Response Controls 5.2 Response Controls
Two response controls are defined to provide feedback while the Two response controls are defined to provide feedback while the
search results are being processed; DuplicateSearchResult and search results are being processed; DuplicateSearchResult and
@ -170,19 +193,11 @@ LDAP Control for a Duplicate Entry Representation of Search Results
operations that contain search results which have been modified by operations that contain search results which have been modified by
the DuplicateEntryRequest control. the DuplicateEntryRequest control.
Sermersheim Internet-Draft - Expires Jan 2001 Page 3
LDAP Control for a Duplicate Entry Representation of Search Results
The DuplicateEntryResponseDone control is sent with the The DuplicateEntryResponseDone control is sent with the
SearchResultDone operation in order to convey completion SearchResultDone operation in order to convey completion
information. information.
4.2.1 The DuplicateSearchResult control 5.2.1 The DuplicateSearchResult control
This control is included in the SearchResultEntry message of any This control is included in the SearchResultEntry message of any
search result that holds an entry that has been modified by the search result that holds an entry that has been modified by the
@ -192,58 +207,45 @@ LDAP Control for a Duplicate Entry Representation of Search Results
DuplicateEntryRequest control. DuplicateEntryRequest control.
The controlType is set to "2.16.840.1.113719.1.27.101.2". The The controlType is set to "2.16.840.1.113719.1.27.101.2". The
criticality is ignored. The controlValue is not included. controlValue is not included.
4.2.2 The DuplicateEntryResponseDone control 5.2.2 The DuplicateEntryResponseDone control
This control is included in the searchResultDone message as part of This control is included in the searchResultDone message as part of
the controls field of the LDAPMessage, as defined in Section 4.1.12 the controls field of the LDAPMessage, as defined in Section 4.1.12
of [RFC2251]. of [RFC2251].
The controlType is set to "2.16.840.1.113719.1.27.101.3". The The controlType is set to "2.16.840.1.113719.1.27.101.3". The
criticality is ignored. The controlValue is an OCTET STRING, whose controlValue is defined as the following DuplicateEntryResponseDone:
value is the BER encoding of the following SEQUENCE:
DuplicateEntryResponseDone ::= SEQUENCE { DuplicateEntryResponseDone ::= SEQUENCE {
resultCode, -- From [RFC2251] resultCode, -- From [RFC2251]
errorMessage [0] LDAPString OPTIONAL, errorMessage [0] LDAPString OPTIONAL,
attribute [1] AttributeDescription OPTIONAL } attribute [1] AttributeDescription OPTIONAL }
A result field is provided here to allow the server to convey to the A resultCode field is provided here to allow the server to convey to
client that an error resulted due to the control being serviced. For the client that an error resulted due to the control being serviced.
example, a search that would ordinarily complete successfully may For example, a search that would ordinarily complete successfully
fail with a sizeLimitExceeded error due to this control being may fail with a sizeLimitExceeded error due to this control being
processed.
Though any result code that is defined in [RFC2251] MAY be returned
the following list assigns special meanings to certain result codes
when returned in this control:
- success: The control was successful.
- timeLimitExceeded Time limit reached before attribute values
could be processed.
- sizeLimitExceeded Size limit reached as a result of this
control.
- adminLimitExceeded result set too large for server to handle.
- unwillingToPerform Server cannot process control.
errorMessage MAY be populated with a human-readable string in the
event of an erroneous result code.
Sermersheim Internet-Draft - Expires Mar 2003 Page 4
Sermersheim Internet-Draft - Expires Jan 2001 Page 4
LDAP Control for a Duplicate Entry Representation of Search Results LDAP Control for a Duplicate Entry Representation of Search Results
attribute MAY be set to the value of the first attribute specified processed. If the operation is successfull, the value will be
by the DuplicateEntryRequest that was in error. The client MUST success (0).
ignore the attribute field if the result is success.
5. Protocol Examples The errorMessage field MAY be populated with a human-readable string
in the event of an erroneous result code.
5.1 Simple example The attribute field MAY be set to the value of the first attribute
specified by the DuplicateEntryRequest that was in error. The
client MUST ignore the attribute field if the result is success.
6. Protocol Examples
6.1 Simple example
This example will show this control being used to produce a list of This example will show this control being used to produce a list of
all telephone numbers in the dc=example,dc=net container. Let's say all telephone numbers in the dc=example,dc=net container. Let's say
@ -284,18 +286,17 @@ LDAP Control for a Duplicate Entry Representation of Search Results
dn: cn=User2,dc=example,dc=net dn: cn=User2,dc=example,dc=net
telephoneNumber: 555-5884 telephoneNumber: 555-5884
Sermersheim Internet-Draft - Expires Mar 2003 Page 5
LDAP Control for a Duplicate Entry Representation of Search Results
control: 2.16.840.1.113719.1.27.101.2 control: 2.16.840.1.113719.1.27.101.2
dn: cn=User3,dc=example,dc=net dn: cn=User3,dc=example,dc=net
telephoneNumber: 555-9425 telephoneNumber: 555-9425
control: 2.16.840.1.113719.1.27.101.2 control: 2.16.840.1.113719.1.27.101.2
Sermersheim Internet-Draft - Expires Jan 2001 Page 5
LDAP Control for a Duplicate Entry Representation of Search Results
dn: cn=User3,dc=example,dc=net dn: cn=User3,dc=example,dc=net
telephoneNumber: 555-7992 telephoneNumber: 555-7992
control: 2.16.840.1.113719.1.27.101.2 control: 2.16.840.1.113719.1.27.101.2
@ -307,55 +308,62 @@ LDAP Control for a Duplicate Entry Representation of Search Results
that is specified in the search filter. This example only does so, that is specified in the search filter. This example only does so,
because the result was to obtain a list of telephone numbers. because the result was to obtain a list of telephone numbers.
5.2 Specifying multiple attributes 6.2 Specifying multiple attributes
A more complicated example involving multiple attributes will result A more complicated example involving multiple attributes will result
in more entries. If we assume these entries in the directory: in more entries. If we assume these entries in the directory:
dn: cn=User1,dc=example,dc=net dn: cn=User1,dc=example,dc=net
givenName: User1 cn: User1
givenName: User One
mail: user1@example.net mail: user1@example.net
dn: cn=User2,dc=example,dc=net dn: cn=User2,dc=example,dc=net
givenName: User2 cn: User2
givenName: User Two givenName: User Two
mail: user2@example.net mail: user2@example.net
mail: usertwo@example.net mail: usertwo@example.net
And both "mail" and "givenName" are specified as attributes in this In this example, we specify mail and name in the attribute list. By
control, the resulting set of entries would be this: specifying name, all attribute subtypes of name will also be
considered. Following is the resulting set of entries:
dn: cn=User1,dc=example,dc=net dn: cn=User1,dc=example,dc=net
givenName: User1 cn: User1
mail: user1@example.net mail: user1@example.net
control: 2.16.840.1.113719.1.27.101.2
dn: cn=User1,dc=example,dc=net
givenName: User One
mail: user1@example.net
control: 2.16.840.1.113719.1.27.101.2
dn: cn=User2,dc=example,dc=net dn: cn=User2,dc=example,dc=net
givenName: User2 cn: User2
mail: user2@example.net mail: user2@example.net
control: 2.16.840.1.113719.1.27.101.2 control: 2.16.840.1.113719.1.27.101.2
dn: cn=User2,dc=example,dc=net dn: cn=User2,dc=example,dc=net
givenName: User2
mail: usertwo@example.net
control: 2.16.840.1.113719.1.27.101.2
dn: cn=User2,dc=example,dc=net Sermersheim Internet-Draft - Expires Mar 2003 Page 6
givenName: User Two
mail: user2@example.net
control: 2.16.840.1.113719.1.27.101.2
dn: cn=User2,dc=example,dc=net
givenName: User Two
mail: usertwo@example.net
control: 2.16.840.1.113719.1.27.101.2
Sermersheim Internet-Draft - Expires Jan 2001 Page 6
LDAP Control for a Duplicate Entry Representation of Search Results LDAP Control for a Duplicate Entry Representation of Search Results
5.3 Listing the members of a groupOfNames cn: User2
mail: usertwo@example.net
control: 2.16.840.1.113719.1.27.101.2
dn: cn=User2,dc=example,dc=net
givenName: User Two
mail: user2@example.net
control: 2.16.840.1.113719.1.27.101.2
dn: cn=User2,dc=example,dc=net
givenName: User Two
mail: usertwo@example.net
control: 2.16.840.1.113719.1.27.101.2
6.3 Listing the members of a groupOfNames
This example shows how the controls can be used to turn a single This example shows how the controls can be used to turn a single
groupOfNames entry into multiple duplicate entries. Let's say this groupOfNames entry into multiple duplicate entries. Let's say this
@ -393,7 +401,12 @@ LDAP Control for a Duplicate Entry Representation of Search Results
This list can then be sorted by member and displayed (also by This list can then be sorted by member and displayed (also by
member) in a list. member) in a list.
6 Relationship to other controls 7. Relationship to other controls
Sermersheim Internet-Draft - Expires Mar 2003 Page 7
LDAP Control for a Duplicate Entry Representation of Search Results
This control is intended (but not limited) to be used with the This control is intended (but not limited) to be used with the
Server Side Sorting control [RFC2891]. By pairing this control with Server Side Sorting control [RFC2891]. By pairing this control with
@ -408,26 +421,20 @@ LDAP Control for a Duplicate Entry Representation of Search Results
The nature of the dependency between the VLV control and the Sort The nature of the dependency between the VLV control and the Sort
control is such that the Sorting takes place first. Because the sort control is such that the Sorting takes place first. Because the sort
happens first, and because this control is processed before the sort happens first, and because this control is processed before the sort
Sermersheim Internet-Draft - Expires Jan 2001 Page 7
LDAP Control for a Duplicate Entry Representation of Search Results
control, the impact of this control on the VLV control is minimal. control, the impact of this control on the VLV control is minimal.
Some server implementations may need to carefully consider how to Some server implementations may need to carefully consider how to
handle the typedown functionality of the VLV control when paired handle the typedown functionality of the VLV control when paired
with this control. The details of this are heavily implementation with this control. The details of this are heavily implementation
dependent and are beyond the scope of this document. dependent and are beyond the scope of this document.
7. Notes for Implementers 8. Notes for Implementers
Both client and server implementations MUST be aware that using this Both client and server implementations MUST be aware that using this
control could potentially result in a very large set of search control could potentially result in a very large set of search
results. Servers MAY return an adminLimitExceeded result in the results. Servers MAY return an adminLimitExceeded result in the
response control due to inordinate consumption of resources. This response control due to inordinate consumption of resources. This
may be due to some a priori knowledge such as a server restriction may be due to some a priori knowledge such as a server restriction
of the number of attribute in the request control that it's willing of the number of attributes in the request control that it's willing
to service, or it may be due to the server attempting to service the to service, or it may be due to the server attempting to service the
control and running out of resources. control and running out of resources.
@ -439,19 +446,24 @@ LDAP Control for a Duplicate Entry Representation of Search Results
pass this control to other servers. Instead they SHOULD gather pass this control to other servers. Instead they SHOULD gather
results and apply this control themselves. results and apply this control themselves.
8. Security Considerations 9. Security Considerations
This control allows finer control of the result set returned by an This control allows finer control of the result set returned by an
LDAP search operation and as such may be used in a denial of service LDAP search operation and as such may be used in a denial of service
attack. See Section 7 for more information on how this is detected attack. See Section 8 for more information on how this is detected
and handled. and handled.
9. Acknowledgments 10. Acknowledgments
The author gratefully thanks the input and support of participants The author gratefully thanks the input and support of participants
of the LDAP-EXT working group. of the LDAP-EXT working group.
10. References 11. References
Sermersheim Internet-Draft - Expires Mar 2003 Page 8
LDAP Control for a Duplicate Entry Representation of Search Results
[RFC2251] [RFC2251]
Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
@ -467,13 +479,7 @@ LDAP Control for a Duplicate Entry Representation of Search Results
Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions Boreham, D, Sermersheim, J, Anantha, A, Armijo, M, "LDAP Extensions
for Scrolling View Browsing of Search Results", Internet Draft, for Scrolling View Browsing of Search Results", Internet Draft,
April, 2000. April, 2000.
Available as draft-ietf-ldapext-ldapv3-vlv-xx.txt.
Sermersheim Internet-Draft - Expires Jan 2001 Page 8
LDAP Control for a Duplicate Entry Representation of Search Results
Available as draft-ietf-ldapext-ldapv3-vlv-04.txt.
[X.511] [X.511]
ITU-T Rec. X.511, "The Directory: Abstract Service Definition", ITU-T Rec. X.511, "The Directory: Abstract Service Definition",
@ -484,7 +490,7 @@ LDAP Control for a Duplicate Entry Representation of Search Results
Levels", Internet Draft, March, 1997. Levels", Internet Draft, March, 1997.
Available as RFC 2119. Available as RFC 2119.
11. Author's Address 12. Author's Address
Jim Sermersheim Jim Sermersheim
Novell, Inc. Novell, Inc.
@ -513,19 +519,4 @@ LDAP Control for a Duplicate Entry Representation of Search Results
Sermersheim Internet-Draft - Expires Mar 2003 Page 9
Sermersheim Internet-Draft - Expires Jan 2001 Page 9