RFC 2967
TISDAG - Technical Infrastructure for Swedish Directory Access Gateways
Pages: 105
Informational
Informational
Part 3 of 5 – Pages 42 to 68
5.8 LDAPv2 DAG-CAP
5.8.1 LDAPv2 DAG-CAP Input
Input to the LDAPv2 DAG-CAP follows the LDAPv2 standard ([19]). Minimally, the LDAPv2 DAG-CAP must support the following queries (adapted from the ASN.1 grammar of the standard): BindRequest ::= [APPLICATION 0] SEQUENCE { version INTEGER (1 .. 127), name LDAPDN, authentication CHOICE { simple [0] OCTET STRING, krbv42LDAP [1] OCTET STRING, krbv42DSA [2] OCTET STRING } } BindResponse ::= [APPLICATION 1] LDAPResult SearchRequest ::= [APPLICATION 3] SEQUENCE { baseObject "dc=se", scope wholeSubtree (2), derefAliases ENUMERATED { neverDerefAliases (0), derefInSearching (1), derefFindingBaseObj (2), derefAlways (3) }, sizeLimit INTEGER (0 .. maxInt), timeLimit INTEGER (0 .. maxInt), attrsOnly BOOLEAN, filter Filter,
attributes SEQUENCE OF AttributeType
}
Filter ::=
CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter
}
SubstringFilter ::=
SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
initial [0] LDAPString,
any [1] LDAPString,
final [2] LDAPString
}
}
Queries against attributes in the prescribed LDAP standard schema
(see Appendix B) are accepted.
N.B., this is a minimal set of supported queries, to achieve the
basic DAG-defined queries. An LDAP DAG-CAP may choose to support
more complex queries than this, if it undertakes to do the
translation from the DAG/IP to the LDAPv2 client in a way that
responds to the semantics of those queries.
TISDAG: Since LDAPv2 didn't specify any characterset but relied
on X.500 to do so, in practice several different charactersets are
in use in Sweden today. That the LDAPv2 CAP has no way of knowing
which characterset that are in use by a connecting client is a
problem that the TISDAG project can not solve.
Users of the DAG system will have to configure their specific
client according to information on the TISDAG web page. That page
provides very specific information (including port number) that
can be given to LDAPv2 users. The LDAP DAG-CAP listening on the
default port (389) will be the LDAPv3 one.
5.8.2 Translation from LDAPv2 query to DAG/IP
Querying the Referral Index The essential stratagem for mapping LDAP queries into DAG/IP Referral Index queries is to tokenize the string-oriented LDAP AttributeValueAssertions or SubstringFilters and construct an appropriate DAG/IP token-oriented query in the DAG/IP. This will generalize the LDAP query and yield false-positive referrals, but should not miss any appropriate referrals. There are 3 particular cases to be considered: equalityMatch queries substring queries combination equalityMatch and substring queries TISDAG: If the LDAP filter contains a cn-term and no objectclass specification it is unclear if the search is for a person or a role. When this happens the DAG query should cover all bases and map the query into a query for both people and roles. EqualityMatch queries can be handled by simply tokenizing the AttributeValueAssertions, making one DAG/IP query term per token (using the appropriate DAGSchema attribute) and carrying out an exact match in the DAG/IP. Consider the following example, represented in the ASCII expression of LDAP Filters as described in [13]): (& (cn=Foo Bar)(objectclass=inetOrgPerson)) This query can be represented in the DAG/IP as FN="Foo" and FN="Bar":search=exact<NL> N.B. The search is set up to be "case=ignore" (the DAG/IP's default) because the relevant LDAP schema attributes are all derivatives of the "name" attribute element, which is defined to have a case insensitive match. If no objectclass were defined the query in DAG/IP would have been (FN="Foo" and FN="bar") or (ROLE="Foo" and ROLE="bar"):search=exact
inetOrgPerson is used as the objectclass in this and the following examples, although person or organizationalPerson could also have been used. This query will yield false-positive referrals; the original LDAP query should only match against records for which the "cn" attribute is exactly the phrase "Foo Bar", whereas the DAG/IP query will yield referrals any WDSP containing records that include the two tokens "foo" and "bar" in any order. For example, this DAG/IP query will yield referrals to WDSPs with records including: cn: Bar Foo cn: Le Bar Foo cn: Foo Bar AB LDAP substring queries must also be tokenized in order to construct a DAG/IP query. The additional point to bear in mind is that LDAP substring expressions are directed at phrases, which obscure potential token boundaries. Consequently, all points between substring components must be considered as potential token boundaries. Thus, the LDAP query (& (cn=black) (o=c*t) (objectclass=inetOrgPerson)) could be expressed as a DAG/IP query with 3 tokens, in a substring search: FN=black and ORG=c and ORG=t:search=substring<NL> This query will yield false-positive results as the tokenized query does not preserve the order of appearance in the LDAP substring, and it doesn't preserve phrase-boundaries. That is, ORG=c and ORG=t:search=substring will match tabacco which is not a match by the LDAP query semantics. Combined EqualityMatch and Substring queries need special attention. When an LDAP query includes both EqualityMatch components and substring filter components, the DAG/IP query to the Referral Index
can be constructed by following the same mechanisms of tokenization, but the whole search will become a substring search, as the DAG/IP defines only search types across the entire query for Referral Index queries. Thus, (& (cn=Foo Bar) (o=c*t) (objectclass=inetOrgPerson)) can be expressed as FN=Foo and FN=Bar and ORG=c and ORG=t:search=substring<NL> Alternatively, the LDAP DAG-CAP could conduct two separate queries and take the intersection (the logical "AND") of the two sets of referrals returned by the Referral Index. Note that DAG/IP can accept phrases for searches -- the query FN=Foo\ bar<NL> (note the escaped space) is perfectly valid. However, it would match only those things which have been tokenized in a way that preserves the space, which is the empty set in the case of the data stored here. Querying a DAG-SAP It is never invalid to use the same substantive query to a DAG-SAP as was used to obtain referral information from the Referral Index. However, the over-generalization of these queries may yield excessive numbers of results, and will necessitate some pruning of results in order to match the returned results against the semantics of the original LDAP query. It is the LDAP DAG-CAP that is responsible for this pruning, as it is the recipient of the original query, and responsible for responding to its semantics. In concrete terms, when making the DAG/IP query which is to be sent to a DAG-SAP the above mentioned queries are still valid queries, but an alternative finer-grained query is also possible, namely: FN=foo and FN=bar and ORG=c;search=lstring and ORG=t;search=tstring Particularly in the case of the LDAPv2 DAG-CAP, however, there will be cause to use LDAP(v2/v3) DAG-SAPs. Since these DAG-SAPs also deal in phrase-oriented data, a less-over-generalized query can be passed to them: FN=Foo\ Bar:search=exact<NL>
In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP), the DAG/IP query must include information about the target WDSP server. This information is drawn from the Referral Index SERVER- TO-ASK referral information, and is appended to the query as specified in Appendix C: ":host=" quoted-hostname ";port=" number ";server-info=" quoted-serverinfo ";charset=" charset where the response from the Referral Index included: "# SERVER-TO-ASK " serverhandle<NL> " Server-info: " serverinfo<NL> " Host-Name: " hostname<NL> " Host-Port: " number<NL> " Protocol: " prot<NL> " Source-URI: " source<NL> " Charset: " charset<NL> "# END<NL> and the "quoted-hostname" and "quoted-serverinfo" are obtained from "hostname" and "serverinfo" respectively, by quoting the DAG/IP special characters. For example, the referral # SERVER-TO-ASK dagsystem01<NL> Server-info: o=thinkingcat, c=se<NL> Host-Name: thinkingcat.com<NL> Host-Port: 2839<NL> Protocol: ldapv2<NL> Source-URI: http://www.thinkingcat.com <NL> Charset: T.61<NL> # END<NL> would yield the addition :host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\ c\=se;charset=T\.61 in its query to an LDAPv2 DAG-SAP. (N.B.: See Appendix C for further definitions of the terms used in the SERVER-TO-ASK response). Note that it is the DAG-SAP's responsibility to extract these terms from the query and use them to identify the WDSP server to be contacted. See the individual DAG-SAP definitions, below.
5.8.3 Chaining queries in LDAPv2 DAG-CAP
The LDAPv2 DAG-CAP relies on DAG-SAPs to resolve every referral.5.8.4 Expression of results in LDAPv2
As described above, results from DAG-SAPs will have to be post- processed in cases where the original query was generalized for expression in DAG/IP. Acceptable results are expressed in the LDAP search response: SearchResponse ::= CHOICE { entry [APPLICATION 4] SEQUENCE { objectName LDAPDN, attributes SEQUENCE OF SEQUENCE { AttributeType, SET OF AttributeValue } }, resultCode [APPLICATION 5] LDAPResult } where LDAPDN = DN / "cn=" (FN/ROLE) [",o="ORG] ",dc=se" attributes = <all attributes mapped from DAG schema, and "objectClass = inetOrgPerson", "objectClass = top", "objectClass = person" or "objectClass = organizationalRole", as appropriate, and "labeledURI = <SOURCE-URI>" for each result from a given referral> (Where DN,FN,ORG and ROLE are the values from the DAG schema). I.e., where available, the entry's true DN is used; otherwise (e.g., for data coming from Whois++ servers), a reasonable facsimile is constructed.5.8.5 Expression of Errors in LDAPv2 DAG-CAP
As appropriate, the LDAPv2 DAG-CAP will express system responses following the LDAPv2 standard.
Appendix D gives the proposed mapping between DAG/IP response codes and LDAPv2 resultcodes. There are 4 particular error conditions of the DAG system that the DAG-CAP will handle as described below. When the LDAPv2 DAG-CAP receives a query that it cannot reply to within the (data) constraints of the DAG queries, it sends an error message and closes the connection. The error message includes the LDAPv2 resultCode: noSuchAttribute (for incorrect schema attributes) inappropriateMatching (when a match type other than those supported is used, e.g. approxMatch) unwillingToPerform (when the query is not one of the defined types) If the number of referrals sent by the Referral Index is greater than the pre-determined maximum (for detecting data-mining efforts, or otherwise refusing over-general queries, such as "FN=svensson"), the LDAPv2 DAG-CAP will send an error message. The error message includes one of the following resultCodes: sizeLimitExceeded timeLimitExceeded An LDAPv2 DAG-CAP may redirect a connection to another LDAPv2 DAG-CAP for reasons of load-balancing. This is expressed to the end-user client software using the "umich referral" convention to direct the client software to an alternate DAG-CAP by passing the URL in an error message. Since a LDAPv2 DAG-CAP only can send one resultcode back to a client; If a LDAPv2 DAG-CAP receives several different result codes from the DAG-SAPs it will have to construct a resultmessage that to some extent represents the combination of those. It is proposed that in these cases the following actions are taken: - All the response codes are collected - Each response code are translated into the corresponding LDAPv2 resultcode. - A resultcode is chosen to represent the collected response on the following grounds: If "success" is the only resultcode represented after these steps the return that result code. If apart from "success" there is one other resultcode represented return that other resultcode.
If apart from "success" there are two or more resultcodes
represented return the resultcode "other".
5.9 LDAPv3 DAG-CAP
5.9.1 LDAPv3 DAG-CAP Input
Input to the LDAPv3 DAG-CAP follows the LDAPv3 definition (currently
defined in [17]). Minimally, the LDAPv3 DAG-CAP must support the
following queries (adapted from the ASN.1 grammar of the standard):
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 }
BindResponse ::= [APPLICATION 1] SEQUENCE {
COMPONENTS OF LDAPResult,
serverSaslCreds [7] OCTET STRING OPTIONAL }
SearchRequest ::= [APPLICATION 3] SEQUENCE {
baseObject c=se,
scope wholeSubtree (2) },
derefAliases ENUMERATED {
neverDerefAliases (0),
derefInSearching (1),
derefFindingBaseObj (2),
derefAlways (3) },
sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
typesOnly BOOLEAN,
filter Filter,
attributes AttributeDescriptionList }
Filter ::= CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter }
SubstringFilter ::= SEQUENCE {
type AttributeDescription,
-- at least one must be present
substrings initial [0] LDAPString,
substrings any [1] LDAPString,
substrings final [2] LDAPString}
Queries against attributes in the proscribed LDAP standard schema
(see Appendix B) are accepted.
N.B., this is a minimal set of supported queries, to achieve the
basic DAG-defined queries. An LDAP DAG-CAP may choose to support
more complex queries than this, if it undertakes to do the
translation from the DAG/IP to the LDAPv3 client in a way that
responds to the semantics of those queries.
5.9.2 Translation from LDAPv3 query to DAG/IP
Querying the Referral Index
The essential stratagem for mapping LDAP queries into DAG/IP Referral
Index queries is to tokenize the string-oriented LDAP
AttributeValueAssertions or SubstringFilters and construct an
appropriate DAG/IP token-oriented query in the DAGschema. This will
generalize the LDAP query and yield false-positive referrals, but
should not miss any appropriate referrals.
There are 3 particular cases to be considered:
equalityMatch queries
substring queries
combination equalityMatch and substring queries
TISDAG: If the LDAP filter contains a cn-term and no objectclass
specification it is unclear if the search is for a person or a
role. When this happens the DAG query should cover all bases and
map the query into a query for both people and roles.
EqualityMatch queries can be handled by simply tokenizing the AttributeValueAssertions, making one DAG/IP query term per token (using the appropriate DAGSchema attribute) and carrying out an exact match in the DAG/IP. Consider the following example, represented in the ASCII expression of LDAP Filters as described in [13]): (& (cn=Foo Bar)(objectclass=person)) This query can be represented in the DAG/IP as FN="Foo" and FN="Bar":search=exact<NL> N.B. The search is set up to be "case=ignore" (the DAG/IP's default) because the relevant LDAP schema attributes are all derivatives of the "name" attribute element, which is defined to have a case insensitive match. If no objectclass where defined the query in DAG/IP would have been (FN="Foo" and FN="bar") or ( ROLE="Foo" and ROLE="bar"):search=exact Although person is used as objectclass in this and the following examples, inetOrgPerson or organizationalPerson could also have been used. This query will yield false-positive referrals; the original LDAP query should only match against records for which the "cn" attribute is exactly the phrase "Foo Bar", whereas the DAG/IP query will yield referrals any WDSP containing records that include the two tokens "foo" and "bar" in any order. For example, this DAG/IP query will yield referrals to WDSPs with records including: cn: Bar Foo cn: Le Bar Foo cn: Foo Bar AB LDAP substring queries must also be tokenized in order to construct a DAG/IP query. The additional point to bear in mind is that LDAP substring expressions are directed at phrases, which obscure potential token boundaries. Consequently, all points between substring components must be considered as potential token boundaries.
Thus, the LDAP query (& (cn=black) o=c*t) (objectclass=person)) should be expressed as a DAG/IP query with 3 tokens, in a substring search: FN=black and ORG=c and ORG=t:search=substring<NL> This query will yield false-positive results as the tokenized query does not preserve the order of appearance in the LDAP substring, and it doesn't preserve phrase-boundaries. That is, ORG=c and ORG=t:search=substring will match tabacco which is not a match by the LDAP query semantics. Combined EqualityMatch and Substring queries need special attention. When an LDAP query includes both EqualityMatch components and substring filter components, the DAG/IP query to the Referral Index can be constructed by following the same mechanisms of tokenization, but the whole search will become a substring search, as the DAG/IP defines search types across the entire query. Thus, (& (cn=Foo Bar) (o=c*t) (objectclass=person)) can be expressed as FN=Foo and FN=Bar and ORG=c and ORG=t:search=substring<NL> Alternatively, the LDAP DAG-CAP could conduct two separate queries and take the intersection (the logical "AND") of the two sets of referrals returned by the Referral Index. Note that DAG/IP can accept phrases for searches -- the query FN=Foo\ bar<NL> (note the escaped space) is perfectly valid. However, it would match only those things which have been tokenized in a way that preserves the space, which is the empty set in the case of the data stored here.
Querying a DAG-SAP It is never invalid to use the same substantive query to a DAG-SAP as was used to obtain referral information from the Referral Index. However, the over-generalization of these queries may yield excessive numbers of results, and will necessitate some pruning of results in order to match the returned results against the semantics of the original LDAP query. It is the LDAP DAG-CAP that is responsible for this pruning, as it is the recipient of the original query, and responsible for responding to its semantics. In concrete terms, when making the DAG/IP query which is to be sent to a DAG-SAP the above mentioned queries are still valid queries, but an alternative finer-grained query is also possible, namely: FN=foo and FN=bar and ORG=c;search=lstring and ORG=t;search=tstring In querying a DAG-SAP (irrespective of the protocol of that DAG-SAP), the DAG/IP query must include information about the target WDSP server. This information is drawn from the Referral Index SERVER- TO-ASK referral information, and is appended to the query as specified in Appendix C): "host=" quoted-hostname ";port=" number ";server-info=" quoted-serverinfo ";charset=" charset where the response from the Referral Index included: "# SERVER-TO-ASK " serverhandle <NL> " Server-info: " serverinfo<NL> " Host-Name: " hostname<NL> " Host-Port: " number<NL> " Protocol: " prot<NL> " Source-URI: " source<NL> " Charset: " charset<NL> "# END"<NL> and the "quoted-hostname" and "quoted-serverinfo" are obtained from "hostname" and "serverinfo" respectively, by quoting the DAG/IP special characters. For example, the referral # SERVER-TO-ASK dagsystem01<NL> Server-info: o=thinkingcat, c=se<NL> Host-Name: thinkingcat.com<NL> Host-Port: 2839<NL> Protocol: ldapv2<NL> Source-URI:http://www-thinkingcat.se/
Charset: T.61<NL>
# END<NL>
would yield the addition
:host=thinkingcat\.com;port=2839;server-info=o\=thinkingcat\,\
c\=se;charset=T\.61
in its query to an LDAPv2 DAG-SAP.
(N.B.: See Appendix C for further definitions of the terms used in
the SERVER-TO-ASK response).
Note that it is the DAG-SAP's responsibility to extract these terms
from the query and use them to identify the WDSP server to be
contacted. See the individual DAG-SAP definitions, below.
5.9.3 Chaining queries in LDAPv3 DAG-CAP
The LDAPv3 DAG-CAP relies on DAG-SAPs to resolve all referrals except
those to LDAPv3 servers (i.e., Whois++ referrals, currently).
5.9.4 Expression of results in LDAPv3
As described above, results from DAG-SAPs will have to be post-
processed in cases where the original query was generalized for
expression in DAG/IP. Acceptable results are expressed in LDAPv3
messages containing search result entries (see the standard for more
detail):
SearchResultEntry ::= [APPLICATION 4] SEQUENCE {
objectName LDAPDN,
attributes PartialAttributeList }
PartialAttributeList ::= SEQUENCE OF SEQUENCE {
type AttributeDescription,
vals SET OF AttributeValue }
SearchResultReference ::= [APPLICATION 19] SEQUENCE OF LDAPURL
-- at least one LDAPURL element must be present
SearchResultDone ::= [APPLICATION 5] LDAPResult
where
LDAPDN = DN / "cn=" (FN/ROLE) [",o=" ORG] ",dc=se"
attributes = <all attributes mapped from the DAG schema, and
"objectClass = inetOrgPerson",
"objectClass = person",
"objectClass = top" or
"objectClass = organizationalRole", as
appropriate, and "labeledURI = <SOURCE-URI>"
for each result from a given referral>
LDAPResult = success
(Where DN, FN, ROLE, and ORG are the values from the DAG schema).
I.e., where available, the entry's true DN is used; otherwise (e.g.,
for data coming from Whois++ servers), a reasonable facsimile is
constructed.
Referral URLs are constructed from the DAG/IP's SERVER-TO-ASK
information as follows:
refurl = "ldap://" HOST [":" PORT] "/" (SERVER-INFO / "dc=se")
The intention is that WDSPs using LDAPv3 servers will provide an
appropriate LDAPDN for their server in the SERVER-INFO. Clients are
then expected to repeat their query at the server designated by this
URL (i.e., the refURL does not include the query).
5.9.5 Expression of Errors in LDAPv3 DAG-CAP
As appropriate, the LDAPv3 DAG-CAP will express operational errors
following the LDAPv3 standard. There are 4 particular error
conditions of the DAG system that the DAG-CAP will handle as
described below.
When the LDAPv3 DAG-CAP receives a query that it cannot reply to
within the (data) constraints of the DAG queries, it sends an error
message and closes the connection. The error message includes the
LDAPv3 resultCode
noSuchAttribute (for incorrect schema attributes chosen)
inappropriateMatching (when a match type other than those
supported is used e.g., approxMatch)
unwillingToPerform (when the query is not one of the defined
types)
If the number of referrals sent by the Referral Index is greater than
the pre-determined maximum (for detecting data-mining efforts, or
otherwise refusing over-general queries, such as "FN=svensson"), the
LDAPv3 DAG-CAP will send an error message. The error message
includes the following resultCode:
adminLimitExceeded
An LDAPv3 DAG-CAP may redirect a connection to another LDAPv3 DAG-CAP
for reasons of load-balancing. In this case, the LDAPv3 DAG-CAP
sends a result message including only
SearchResultReference ::= [APPLICATION 19] AltURL
SearchResultDone ::= referral
where
AltURL = "ldap://" <althostport> ":" <altbase>
Since a LDAPv3 DAG-CAP only can send one resultcode back to a client;
If a LDAPv3 DAG-CAP receives several different result codes from the
DAG-SAPs it will have to construct a resultmessage that to some
extent represents the combination of those. It is proposed that in
these cases the following actions are taken:
- All the response codes are collected
- Each response code are translated into the corresponding LDAPv3
resultcode.
- A resultcode is chosen to represent the collected response on the
following grounds:
If "success" is the only resultcode represented after these steps
the return that result code.
If apart from "success" there is one other resultcode represented
return that other resultcode.
If apart from "success" there are two or more resultcodes
represented return the resultcode "other".
5.10 Whois++ DAG-SAP
5.10.1 Input
The Whois++ DAG-SAP expects valid DAG/IP communications. Queries
must include referral information (see below) and search terms that
conform to the DAG-allowed query types (e.g., not searches for
organization alone, etc).
The referral information is added to the end of the DAG-SAP query, as
defined in the DAG-CAP definition sections:
":host=" quoted-hostname ";port=" number ";server-info="
quoted-serverinfo ";charset=" charset
5.10.2 Translation from DAG/IP to Whois++ query
The HOST and PORT information are used to make a TCP/IP-based connection to the remote (presumed) Whois++ server. The query expressed to the remote Whois++ server is the remainder of the DAG/IP query the Whois++ DAG-SAP received, with the following template ID translations: template=DAGPERSON becomes template=USER and template=DAGROLE becomes template=ORGROLE Additional mappings for attributes are defined in Appendix B. Note that the search types used in the DAG/IP are not all required by the Whois++ syntax. Therefore, some Whois++ WDSPs may be using servers that do not support searches other than "exact" and "lstring" (the search types required by the Whois++ protocol standard). The Whois++ DAG-CAP may - send the DAG/IP query as constructed (e.g., with "search=substring"), and pass back the "% 502 Search expression too complicated" from the WDSP's server, - translate the DAG/IP query into a construct using only these search types (which will yield incomplete results, as not all queries are expressible with those search types), - attempt to ascertain what search types are supported by the remote server and reformulate using them (e.g., regular expressions). This would work, but would entail an excessively complicated Whois++ DAG-SAP, and might not yield any better results if the remote server doesn't support any optional search types.5.10.3 Translation of Whois++ results to DAG/IP
Any referrals that the remote WDSP server returns are pursued, following the usual Whois++ (client) fashion, by the Whois++ DAG-SAP. If it is not possible to establish a Whois++ session with the remote server, or if the session is interrupted, before results are received, the DAG-SAP will itself return no results and an error message, including % 403 Information Unavailable<NL>
If the remote server issues any other Whois++ error message and does not yield any results, the remote server's error message will be included in the DAG-SAP's own error message; no results will be returned. If results are successfully received from the remote server, they will be expressed using the DAG/IP -- essentially passing through all FULL response information received from the remote server, mapped into the DAGSchema using the mappings defined in Appendix A.5.11 LDAPv2 DAG-SAP
5.11.1 Input
The LDAPv2 DAG-SAP expects valid DAG/IP communications. Queries must include referral information (see below) and search terms that conform to the DAG-allowed query types (e.g., not searches for organization alone, etc). The referral information is added to the end of the DAG-SAP query, as defined in the DAG-CAP definition sections (as additional terms in the DAG/IP query): ":host=" quoted-hostname ";port=" number ";server-info=" quoted-serverinfo ";charset=" charset5.11.2 Translation from DAG/IP to LDAPv2 query
The HOST and PORT information are used to make a TCP/IP-based connection to the remote (presumed) LDAPv2 server. The DAG-SAP will establish a connection with the remote server, following standard LDAPv2 message exchanges. The search request itself will be constructed from the DAG/IP query (without the HOST, SERVER-INFO and PORT terms) as follows: SearchRequest ::= [APPLICATION 3] SEQUENCE { baseObject LDAPDN, -- from the DAG/IP query scope baseObject (0) }, derefAliases ENUMERATED { neverDerefAliases (0), derefInSearching (1), derefFindingBaseObj (2), derefAlways (3) }, sizeLimit INTEGER (0 .. maxInt),
timeLimit INTEGER (0 .. maxInt),
attrsOnly FALSE
filter Filter,
attributes SEQUENCE OF AttributeType
-- all DAGschema attributes
equivalents in the defined
standard LDAP schema
}
Filter ::=
CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
substrings [4] SubstringFilter,
}
SubstringFilter
SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
substrings initial [0] LDAPString,
substrings any [1] LDAPString,
substrings final [2] LDAPString}
}
where and, or and not filters are constructed to preserve the logic
of the DAG/IP query.
For the purposes of matching token-based DAG/IP queries to reasonable
LDAP queries, all searches should be passed to the LDAP WDSP as
substring searches. The WDSP results must then be pruned to respect
token boundaries, where necessary.
So, for example, the DAG/IP query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=substring<NL>
would be sent to the designated LDAP WDSP as
(& (fn=*Foo Bar*) (o=*Thinking Cat*) (objectclass=person))
Interestingly, the query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=exact<NL>
would also be sent to the designated LDAP WDSP as
(& (fn=*Foo Bar*) (o=*Thinking Cat*) (objectclass=person)) but the WDSPs returned results would have to be pruned to remove any results that had non-tokenizing characters on either side of "Foo Bar" and "Thinking Cat". The final consideration for mapping DAG/IP queries into LDAP queries is the issue of character case. In LDAP, individual attribute syntaxes define the consideration of case. All of the attributes used here are case-insensitive in their definitions. Therefore, all LDAP WDSP queries are inherently case-insensitive; if the DAG/IP query calls for a case-sensitive match, the LDAP DAG-SAP will have to do pruning of the results from the DAG-SAP.5.11.3 Translation of LDAPv2 results to DAG/IP
If it is not possible to establish an LDAPv2 session with the remote server, or if the session is interrupted before results are received, or if the remote server issues any kind of error message and produces no result, the DAG-SAP will itself return no results and an error message, including % 403 Information Unavailable<NL> If results are successfully received from the remote server, the attributes and values that are provided for each result message will be incorporated into the DAG/IP result, according to the schema mappings laid out in Appendix B. One particular adjustment must be done to accommodate differences between LDAP and the DAG/IP. The attributes on which searches are keyed ("cn", "l", and "o" in the LDAP schemas) are all defined as being case-insensitive for equality matching. Thus, if the DAG/IP query includes the constraint "case=consider", the results from the remote server must be post-processed to remove any wrong-cased ones. TISDAG: The serverhandle and localhandle in the DAG/IP response should be constructed as follows: serverhandle is: <hostname-without-periods><port> (because server DN's are not enforceably unique). E.g., a services.bunyip.com server on 7778 would become servicesbunyipcom7778. localhandle is: the RDN (relative distinguished name), with spaces replaced by "_". E.g., cn=leslie_daigle
5.12 LDAPv3 DAG-SAP
5.12.1 Input
The LDAPv3 DAG-SAP expects valid DAG/IP communications. Queries must include referral information (see below) and search terms that conform to the DAG-allowed query types (e.g., not searches for organization alone, etc). The referral information is added to the end of the DAG-SAP query, as defined in the DAG-CAP definition sections: ":host=" quoted-hostname ";port=" number ";server-info=" quoted-serverinfo ";charset=" charset5.12.2 Translation from DAG/IP to LDAPv3 query
The HOST and PORT information are used to make a TCP/IP-based connection to the remote (presumed) LDAPv3 server. The DAG-SAP will establish a connection with the remote server, following standard LDAPv3 message exchanges. The search request itself will be constructed from the DAG/IP query (without the HOST, SERVER-INFO and PORT terms) as follows: SearchRequest ::= [APPLICATION 3] SEQUENCE { baseObject LDAPDN, -- from the DAG/IP query scope baseObject (0) }, derefAliases ENUMERATED { neverDerefAliases (0), derefInSearching (1), derefFindingBaseObj (2), derefAlways (3) }, sizeLimit INTEGER (0 .. maxInt), timeLimit INTEGER (0 .. maxInt), attrsOnly FALSE filter Filter, attributes SEQUENCE OF AttributeType -- all DAGschema attributes equivalents in the defined standard LDAP schema } Filter ::= CHOICE { and [0] SET OF Filter, or [1] SET OF Filter,
not [2] Filter,
substrings [4] SubstringFilter,
}
SubstringFilter
SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
substrings initial [0] LDAPString,
substrings any [1] LDAPString,
substrings final [2] LDAPString}
}
where and, or and not filters are constructed to preserve the logic
of the DAG/IP query.
For the purposes of matching token-based DAG/IP queries to reasonable
LDAP queries, all searches should be passed to the LDAP WDSP as
substring searches. The WDSP results must then be pruned to respect
token boundaries, where necessary.
So, for example, the DAG/IP query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=substring<NL>
would be sent to the designated LDAP WDSP as
(&(fn=*Foo Bar*)(o=*Thinking Cat*)(objectClass=person))
Interestingly, the query
FN=Foo\ Bar and ORG=Thinking\ Cat:search=exact<NL>
would also be sent to the designated LDAP WDSP as
(&(fn=*Foo Bar*)(o=*Thinking Cat*)(objectClass=person))
but the WDSP's returned results would have to be pruned to remove any
results that had non-tokenizing characters on either side of "Foo
Bar" and "Thinking Cat".
The final consideration for mapping DAG/IP queries into LDAP queries
is the issue of character case. In LDAP, individual attribute
syntaxes define the consideration of case. All of the attributes
used here are case-insensitive in their definitions. Therefore, all
LDAP WDSP queries are inherently case-insensitive; if the DAG/IP
query calls for a case-sensitive match, the LDAP DAG-SAP will have to
do pruning of the results from the DAG-SAP.
5.12.3 Translation of LDAPv3 results to DAG/IP
Any referrals that the remote WDSP server returns are pursued, following the usual LDAPv3 (client) fashion, by the LDAPv3 DAG-SAP. If it is not possible to establish an LDAPv3 session with the remote server, or if the session is interrupted before results are received, or if the remote server issues any kind of error message and produces no result, the DAG-SAP will itself return no results and an error message, including % 403 Information Unavailable<NL> If results are successfully received from the remote server, the attributes and values that are provided for each result message will be incorporated into the DAG/IP result, which will be expressed using the DAG/IP and schema mappings as outlined in Appendix A. One particular adjustment must be done to accommodate differences between LDAP and the DAG/IP. The attributes on which searches are keyed ("cn", "l", and "o" in the LDAP schemas) are all defined as being case-insensitive for equality matching. Thus, if the DAG/IP query includes the constraint "case=consider", the results from the remote server must be post-processed to remove any wrong-cased ones. TISDAG: The serverhandle and localhandle in the DAG/IP response should be constructed as follows: - serverhandle is: <hostname-without-periods><port> (because server DN's are not enforceably unique). E.g., a services.bunyip.com server on 7778 would become servicesbunyipcom7778. - localhandle is: the RDN (relative distinguished name), with spaces replaced by "_". E.g., cn=leslie_daigle5.13 Example Queries
The following sample end-user queries illustrate some of the more delicate steps of query/schema semantics translations in the DAG system. N.B.: the data presented in these examples is often senseless, provided only to serve as illustrations of matching on word-ordering, case sensitivity, etc.
5.13.1 A Whois++ Query
What the Whois++ DAG-CAP Receives In this example, the Whois++ DAG-CAP receives the following query: name=thinking and name=cat:search=exact;case=consider<NL> The expected answer can be described as: Any USER templates that contain the tokens "thinking" and "cat" in a name attribute. For example: Different records: name: the thinking cat name: sublime cat thinking or a single record with 2 or more name attributes name: thinking felines name: erudite cat but not name: Thinking Cat Enterprises This last record would not match because the query called for case sensitivity, and the case of the name attribute's value does not match the query. What the Whois++ DAG-CAP sends to the Referral Index After schema translation, this is sent to the Referral Index as: fn=thinking and fn=cat:search=exact<NL> What the Whois++ DAG-CAP Sends to an LDAP DAG-SAP Note that the Whois++ DAG-CAP will never interact with a Whois++ DAG-SAP as the Whois++ referrals returned by the Referral Index are passed directly back to the Whois++ client. The Whois++ DAG-CAP should send the same substantive query to the DAG-SAP as it sent to the Referral Index, except that it can include the case sensitivity constraint:
fn=thinking and fn=cat:search=exact;case=consider<NL> which will be translated by the DAG-SAP into an LDAP query of the form: (&(cn=*thinking*)(cn=*cat*)(objectclass=inetOrgPerson)) which will match a record with: cn: Thinking cn: Cat (i.e., 2 different cn attributes, with the 2 values; LDAP defines case sensitivity matching by the schema attribute definition). or a record with: cn: I wish I had a thinking dog and a singing cat The first record should be pruned by the LDAP DAG-SAP, in order to respect the semantics of the DAG/IP query.5.13.2 An LDAP Query
What the LDAP DAG-CAP Receives In this example, the LDAP DAG-CAP receives the following query (using RFC1960 notation): (& (cn=th*c*t) (o=green groceries) (objectClass=person)) What the LDAP user is looking for, with this query, is all records within the "green groceries" organization that have a cn attribute starting with "th", ending with "t", and having a "c" somewhere in the middle. cn values that would match this include: cn: thinkingcat cn: Thinking Cat cn: The Black Cat cn: Thick Mat
5.13.3 What the LDAP DAG-CAP sends to the Referral Index
The LDAP DAG-CAP must formulate a token-based query to the Referral Index that will not inadvertently exclude records that would match. The first challenge lies in the fact that the "*" characters in the LDAP string-based query can cover token-boundaries. A suitable query to the Referral Index would be: FN=th AND FN=C AND FN=T AND ORG=green AND ORG=groceries:search=substring<NL> This will generate some false positive referrals, directing the query to WDSPs containing records with the following attribute values (the match letters are in capitals for ease of identification): cn: wiTH three blaCk poTs o: peaGREEN and cyan GROCERIES o: GROCERIES are GREENer than electronics Alternative approaches include breaking the original query into several queries to the referral index in such a way that the DAG-CAP can use only those referrals that appear in all the Referral Index responses. However, this is overkill -- the purpose of the Referral Index is to give direction on where there may be more information difficult to code into the DAG-CAP in a general way -- it has to identify, by LDAP query type, when and how to do so likely to generate Referral Index queries that are complex and time- consuming to process. What the LDAP DAG-CAP Sends to a Whois++ DAG-SAP The LDAP DAG-CAP may send the same query to a Whois++ DAG-SAP as it sent to the Referral Index. False positives here mean results that are not expected as a match by the LDAP client. The LDAP DAG-CAP should prune these results from the information returned by the Whois++ DAG-SAP. Or it might rewrite the query into: FN=th;search=lstring AND FN=C;search=substring AND FN=T;search=tstring AND ORG=green AND ORG=groceries:case=ignore<NL>
What the LDAP DAG-CAP Sends to an LDAP DAG-SAP As an architectural principle, it is never wrong to send the same query to a DAG-SAP as was formulated for the Referral Index. It is also noteworthy to keep in memory that all DAG-SAPs are handled equal by all DAG-CAPs therefore a LDAP DAG-CAP will not need to send a different query to a LDAP DAG-SAP then it would to any other DAG-SAP. So in this case the LDAP DAP-CAP could either send the same query to the LDAP DAG-SAP as it sent to the Referral Index or it could send the augmented version that is allowed to be use with the DAG-SAPs, namely: FN=th;search=lstring AND FN=C;search=substring AND FN=T;search=tstring AND ORG=green\ groceries:case=ignore<NL> Note that this will be translated, by the LDAP DAG-SAP, into a query of the form (&(cn=*th*)(cn=*c*)(cn=*t*)(o=*green groceries*) (objectClass=person)) which is still more general than the original query. Note the translation from "FN=th;search=lstring" into "cn=*th*". This is necessary, as the DAG/IP lstring constraint is based on tokens, whereas "cn=th*" refers to the beginning of the attribute's value (phrase, not token). The DAG-SAP should therefore prune out any results that include things like "oTHer plaCes for visiTors" in order to match the semantics of the DAG/IP query it received. The DAG-CAP should then prune those results to match the semantics of the original LDAP query.
(page 68 continued on part 4)