[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Another approach to an XML directory service
Hello, Let me introduce myself. My name is Andy Newton, and I work for VeriSign. With our experience in DNS and whois, we have been doing a lot of thinking about directory services. In February, we submitted three drafts to the IETF on an idea we call XDAP. I'm attaching the text to this e-mail to further the discussion on the scope, limits, and possibilities of DSML. I also think that OASIS may be a better forum to express these ideas. XDAP is not an LDAP-centric service, but I thought it might be a good idea to mention it given some of the talk about SOAP, SAML, etc.. You can also find the HTML version on the web: http://www.cto.netsol.com/home.php?inc=projects.inc&content=projects/xdap/draft-newton-xdap-00.html http://www.cto.netsol.com/home.php?inc=projects.inc&content=projects/xdap/draft-newton-xdap-domdir-00.html http://www.cto.netsol.com/home.php?inc=projects.inc&content=projects/xdap/draft-newton-xdap-ipdir-00.html Here is a brief summary of the drafts: XDAP itself is a light framework for specifying search and access operations, and for expressing search continuations and entity references. It utilizes XML namespaces and XML schemas to accomplish this. We have provided two directory service "applications" that use XDAP. DOMDIR is an XDAP directory service for querying DNS domain name registration data, and IPDIR is an XDAP directory service for querying IP network administration data. We even thought of publishing a draft on using DSML on top of XDAP. Our motivations behind XDAP: Before attempting XDAP, we seriously looked at LDAP to build a better "whois". And while we readily admit that LDAP is by far more feature rich than the whois protocol, we found it did not solve all of the problems associated with domain names and IP addresses, especially as it would relate to IP registries and routing administration. You can find our work on this at http://www.ldap.research.netsol.com/ . Briefly, here are some of the goals we were after with XDAP, mostly gained from our learning experience with LDAP: o The strict naming hierarchy of LDAP does not apply to all types of directory services. This is especially true when dealing with IP networks divided on class-less boundaries (CIDR). Therefore, the ability to specify the hierarchy based on the application of the service is desirable. o Though LDAP provides for a structured query grammar, some searches are deemed expensive or not allowed at all for business reasons (there is a terrible amount of third-party data-mining that goes on in the whois circles). Once we disabled some LDAP searches, it became clear that not only did we have to publish which searches were allowed, but special clients talking LDAP would have to be created to correctly search the service. Therefore, it makes sense to expressly define the searches allowed per type of directory application. o One of our biggest headaches with LDAP deals with referrals, which we made a central theme to our project to deal with the differences between the data stored in a domain registry and the various client domain registrars. It seems no two LDAP clients (command line clients at least) act the same way in dealing with LDAP referrals. In addition, because LDAP specifies that referrals are always returned if in scope regardless of the search filter, we encountered situations where a search against an LDAP server would produce only referrals due to time and result limits. Our conclusion was that there is a difference between a search continuation and an entity reference. Also, the specified directory application should be able to determine when they are in or out of scope. Anyway, I hope this provokes discussion and that you consider some of the ideas presented here. -andy -- Andrew Newton VeriSign Applied Research anewton@research.netsol.com
Network Working Group A.L. Newton
Internet-Draft VeriSign, Inc.
Expires: August 23, 2001 February 22, 2001
eXtensible Directory Access Protocol
draft-newton-xdap-00
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 23, 2001.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract
This document describes an application layer client-server protocol
for a framework of representing the query and result operations of
directory services. Specified in XML, the protocol defines generic
directory query and result operations and a mechanism for extending
these operations for specific directory service needs.
Newton Expires August 23, 2001 [Page 1]
Internet-Draft eXtensible Directory Access Protocol February 2001
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 Use of XML . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 General Concepts . . . . . . . . . . . . . . . . . . . . . . 3
2. Protocol Description . . . . . . . . . . . . . . . . . . . . 5
2.1 Protocol Identification . . . . . . . . . . . . . . . . . . 5
2.2 Request Format . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.1 <authenticate> Request . . . . . . . . . . . . . . . . . . . 6
2.2.2 <sessionInquiry> and <serviceInquiry> Request . . . . . . . 6
2.2.3 <directorySearch> Request . . . . . . . . . . . . . . . . . 7
2.2.4 <quit> Request . . . . . . . . . . . . . . . . . . . . . . . 7
2.3 Response Format . . . . . . . . . . . . . . . . . . . . . . 7
2.3.1 <sessionStatus> Response . . . . . . . . . . . . . . . . . . 7
2.3.2 <serviceResult> Response . . . . . . . . . . . . . . . . . . 8
2.3.3 <directoryResult> Response . . . . . . . . . . . . . . . . . 8
3. Extension Framework . . . . . . . . . . . . . . . . . . . . 10
3.1 Derived Elements . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Namespace Identifier Requirements . . . . . . . . . . . . . 10
3.3 Names of Entities . . . . . . . . . . . . . . . . . . . . . 11
4. URI Requirements . . . . . . . . . . . . . . . . . . . . . . 12
5. Formal XML Syntax . . . . . . . . . . . . . . . . . . . . . 13
6. Internationalization Considerations . . . . . . . . . . . . 19
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 20
8. Security Considerations . . . . . . . . . . . . . . . . . . 21
References . . . . . . . . . . . . . . . . . . . . . . . . . 22
Author's Address . . . . . . . . . . . . . . . . . . . . . . 23
A. Expressing a Base in XDAP . . . . . . . . . . . . . . . . . 24
B. Schema Discovery . . . . . . . . . . . . . . . . . . . . . . 26
C. An Example Directory Namespace . . . . . . . . . . . . . . . 27
C.1 Part Number Schema . . . . . . . . . . . . . . . . . . . . . 27
C.2 Example Login . . . . . . . . . . . . . . . . . . . . . . . 29
C.3 Example Service Inquiry . . . . . . . . . . . . . . . . . . 29
C.4 Example Search . . . . . . . . . . . . . . . . . . . . . . . 30
C.5 Another Example Search . . . . . . . . . . . . . . . . . . . 32
C.6 Example Entity Lookup . . . . . . . . . . . . . . . . . . . 33
D. Document Terminology . . . . . . . . . . . . . . . . . . . . 35
Full Copyright Statement . . . . . . . . . . . . . . . . . . 36
Newton Expires August 23, 2001 [Page 2]
Internet-Draft eXtensible Directory Access Protocol February 2001
1. Introduction
1.1 Use of XML
This document describes the specification for the eXtensible
Directory Access Protocol (XDAP), an XML text protocol with the
purpose of describing the query types and result types of various
directory services. XDAP is specified using the Extensible Markup
Language (XML) 1.0 as described in [1], XML Schema notation as
described in [3] and [4], and XML Namespaces as described in [2].
It is important to note that XML is case sensitive. XML
specifications and examples provided in this document MUST be
interpreted in the exact character case presented to develop a
conforming implementation.
1.2 General Concepts
The use of an electronic directory and its associate parts and
components to accomplish a certain task or set of tasks is generally
considered a directory application. The knowledge of the structure
of names of entities, the sub-components of these entities, and the
understanding of the query syntax to find these entities are all
applied to execute the tasks. This document calls this knowledge of
the directory and how to use it a directory namespace. This
directory namespace is identified by the URI, more specifically a
URN, used within the XML instances to identify the XML schema
formally describing the directory.
A directory service, or a process running on a computer serving
directory information, may handle queries and serve results for
multiple directory namespaces. Each directory namespace for which a
particular directory service serves is a directory instance.
XDAP, and the XML schema formally describing XDAP, does not specify
any directory, directory namespace, or knowledge of a particular
directory application. XDAP is a specification for a framework with
which these directory namespaces can be defined, used, and in some
cases interoperate. The framework merely specifies the elements for
session management and the elements which must be used to derive
query elements and result elements.
This framework allows a directory namespace to define its own
structure for naming, entities, queries, etc. through the use XML
namespaces and XML schemas (hence, a directory is identified by the
same URI that identifies its XML namespace). In order to be useful,
a directory namespace must extend from this framework.
The framework does define certain structures that can be common to
Newton Expires August 23, 2001 [Page 3]
Internet-Draft eXtensible Directory Access Protocol February 2001
all directory namespaces, such as entity references, search
continuations, authentication types, and more. A directory
namespace may declare its own definitions for all of these, or it
may mix its derived definitions with the base definitions.
XDAP defines two types of referrals, an entity reference and a
search continuation. An entity reference indicates specific
knowledge about an individual entity, and a search continuation
allows for distributed searches. Both types may span differing
directory namespaces and instances. In addition, XDAP specifies
requirements for representing entity references as URI's. No
assumptions or specifications are made about roots, bases, or meshes
of entities.
Finally, the XDAP framework attempts to be transport neutral. There
is no default transport specification
Newton Expires August 23, 2001 [Page 4]
Internet-Draft eXtensible Directory Access Protocol February 2001
2. Protocol Description
XDAP is an application layer protocol that can be layered over
multiple transport protocols. Each protocol data unit MUST be one
and only one complete and valid XML instance. The XML document MAY
contain one request element and MAY contain one response element.
The request element describes elements for a client to authenticate
to a server, request session status information, inquire about the
available directory data sets, query a directory data set, and close
the session.
The response element describes elements for a server to provide to a
client session status, available directory data sets, and results
from a directory query.
No requirements are made concerning the synchronization of the
request and the response in this document. However, a transport
mapping of XDAP MAY make such requirements if necessary. Both the
request and response elements have optional 'sessionToken'
attributes to aid in synchronization. In this specification they
are OPTIONAL, however a transport mapping MAY require them.
The definition of a session is dependent on the underlying
transport, but is generally understood to be the context in which
requests and responses are conducted with respect to authentication.
The following description of the protocol does not describe every
detailed aspect necessary for implementation. While reading these
following sections, please reference Section 5 for needed details on
the formal XML specification.
2.1 Protocol Identification
The root element of all XDAP instance documents must be <xdap>.
This element identifies the start of the XDAP elements, the
namespace used as the identifier for the XDAP namespace, and the
location of the schema. This element and the associated closing tag
MUST be applied to all requests and responses sent by both clients
and servers.
An example:
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd">
</xdap>
The use of the schema location URI in the <xsi:schemaLocation>
Newton Expires August 23, 2001 [Page 5]
Internet-Draft eXtensible Directory Access Protocol February 2001
element is OPTIONAL with respect to its use by this specification,
and XDAP implementations MAY resolve it to retrieve the schema or
they MAY use a locally cached version of the schema. The presence of
this URI is mandatory according to [4]. The URI MUST be a valid URI,
and SHOULD resolve if the appropriate network resources are
available.
Versioning of the XDAP protocol is accomplished by use of the
namespace URI. A change in the URI indicates a change of the
underlying schema and therefore a new version of the protocol.
2.2 Request Format
A <request> element holds children representing the different
requests that can be made from a client to a server. This element
has one attribute, 'sessionToken'. This attribute is a string of
generated by the client and SHOULD NOT have any meaning to the
server. Its purpose is to provide a mechanism for use by the client
to match requests with responses, and it MAY be absent or empty.
2.2.1 <authenticate> Request
Providing a mechanism for authentication, this element may have
children of <simpleAuthentication> or derivatives of
<complexAuthentication>. The simple case requires
<authenticationId> and <authenticationPassword>. The complex case is
an abstract element to be defined by in the namespace of
directories. Each type MUST contain an attribute of
'directoryNamespace' signifying the target directory namespace to
apply this authentication. This value of this and directory
namespace of a derived complex authentication element MAY be
different.
A client MAY reauthenticate more than once during session using the
<authenticate> request. If reauthentication occurs with different
credentials, all new requests are to be processed against the new
credentials. Outstanding requests are to be processed against the
old credentials.
The specification for a directory namespace MAY choose to explicitly
deny authentication using <simpleAuthentication>.
2.2.2 <sessionInquiry> and <serviceInquiry> Request
The <sessionInquiry> element allows the client to inquire about the
current session it has with the server. This element has not
content and no attributes. Clients SHOULD start sessions with a
session inquiry.
Newton Expires August 23, 2001 [Page 6]
Internet-Draft eXtensible Directory Access Protocol February 2001
The <serviceInquiry> element enables the client to query for a list
of directory namespace identifiers. Authentication MUST not be
required for this request.
2.2.3 <directorySearch> Request
The <directorySearch> element enables a client to query a directory
namespace of a directory service. It may have two element types as
children: <lookupEntity> and <query>.
The content of the <lookupEntity> element is the name of an entity
within a directory. The 'directoryNamespace' attribute is the
namespace identifier for the directory in which the lookup operation
is to take place.
The <query> element is abstract and MAY NOT legally appear in an XML
instance. It provides the base type to be used by directory
namespaces to define derived query types.
2.2.4 <quit> Request
The <quit> element signals the clients intent to close the session.
If the <request> element containing a <quit> element does not
contain a <directorySearch>, <sessionInquiry>, or <serviceInquiry>
element, the server MUST immediately close the session, else the
server MUST respond with the results and then immediately close the
session.
2.3 Response Format
The <response> element holds children of the different response
types returned from a server to a client. This element has one
attribute, 'sessionToken'. This attribute is a string generated by
the client and SHOULD NOT have any meaning to the server. The value
of this attribute MUST be identical to the value of the
'sessionToken' attribute of the corresponding <request> element.
2.3.1 <sessionStatus> Response
The <sessionStatus> element MUST be returned to the client in
response to an <authenticate> or <sessionInquiry> request. This
element MUST also be returned to the client when authentication is
required in response to <directorySearch> requests.
The <sessionStatus> MUST contain one of these child elements:
o <currentlyAuthenticated> MUST be the response if the client
issues an <authenticate> request. If the client issues a
<sessionInquiry> request and the client is authenticated by means
Newton Expires August 23, 2001 [Page 7]
Internet-Draft eXtensible Directory Access Protocol February 2001
of a lower layer protocol, the server MUST respond with this
answer. If the client issues an <authenticate> request and is
already authenticated by means of a lower layer protocol, the
server MUST respond with this answer regardless of the
authentication credentials in the <authenticate> method.
o <authenticationRequired> MUST be the child of <sessionStatus> if
authentication is required to proceed with any requests, or in
response to a <sessionInquiry> request when the client is not
authenticated.
o <noAuthenticationRequired> MUST be the child of <sessionStatus>
if no authentication is required, or in response to a
<sessionInquiry> request when the client is not required to
authenticate.
The <sessionStatus> element MAY contain the <communicationProblem>
element. This element signifies the failure to correctly parse the
XML of the corresponding request.
2.3.2 <serviceResult> Response
The <serviceResult> element is a response to the <serviceInquiry>. A
server MAY require authentication before serving this information.
If authentication is required and the client is not authenticated, a
server MUST return a <sessionStatus> element instead of a
<serviceResult> element.
If the client is authenticated, this element MUST contain child
elements of <directoryNamespace>. The contents of each child MUST
contain one directory namespace identifier. In this state, the
<serviceResult> element MUST contain a <directoryNamespace> child
element for each directory namespace for which the server allows
queries.
A server MAY NOT require separate authentication credentials for
this response than for the <directoryResult> response. In other
words, if a client is a authenticated to receive <directoryResult>
responses, then it MUST also be authenticated to receive these
responses.
2.3.3 <directoryResult> Response
The <directoryResult> element is a response to a <directorySearch>
request. Each child element is a response to a corresponding child
element in the <directorySearch> request element, and the order of
these children MUST be the same order as their corresponding request
elements.
Newton Expires August 23, 2001 [Page 8]
Internet-Draft eXtensible Directory Access Protocol February 2001
The children MUST be one of the following types:
o <result> is an abstract element and MAY NOT be legally placed in
an XML instance. It provides the base type to be used by
directory namespaces to define derived result types.
o The contents of <entityReference> is a URI. This element
notifies the client of a reference to an entity. The URI SHOULD
be an XDAP URI. Resolution of the URI is OPTIONAL by the client.
o The <searchContinuation> element children MUST contain one
<hostReference> element and one <directorySearch> element.
Directory namespaces MAY derive a new type from <hostReference>
to match transport protocol needs.
o The following error elements:
* <insufficientResources> - the corresponding query requires
resources unobtainable by the server.
* <invalidName> - a name given in a query is not syntactically
correct.
* <invalidSearch> - parameters of the corresponding query are
not semantically meaningful.
* <limitExceeded> - the corresponding query requires more
resources than allowed.
* <nameNotFound> - the name given in a query does not match a
known entity.
* <permissionDenied> - the authentication given does not allow
access to a specific result entry. This is not the same as
denying access to all <directoryResult> responses because of
failed authentication.
* <invalidXML> - the XML of the directory namespace of the
corresponding query does not validate.
Newton Expires August 23, 2001 [Page 9]
Internet-Draft eXtensible Directory Access Protocol February 2001
3. Extension Framework
Because the XDAP schema defines no useful query types, no directory
structure, and no result types, it is useless by itself. Extension
of XDAP is accomplished through the use a base XDAP schema, as
defined in [3] and [4], and extension of it by directories
constructed on top of XDAP.
3.1 Derived Elements
The XML Schema definition of XDAP requires schemas of directory
namespaces to derive element types from base types in the XDAP
definition. The schema definitions of directory namespaces SHOULD
derive elements for definition of typed queries and results.
While the XDAP schema definition does not prohibit the derivation of
any elements, directory namespace schemas SHOULD restrict the
derivations to the following types:
o <query> - as defined this element contains no content and has no
valid attributes. It is abstract and therefore only derivatives
of it MAY appear in an XML instance.
o <result> - as defined this element contains no content and has no
valid attributes. It is abstract and therefore only derivatives
of it MAY appear in an XML instance.
o <hostReference> - as defined this element contains a <scheme>,
<host>, and <port> elements. Derivations SHOULD extend the
content to include information necessary establishing sessions by
lower layer protocols, but SHOULD NOT restrict derivations to
content less than what is defined.
o <complexAuthentication> - as defined this element contains no
content and has one valid attribute, 'directoryNamespace'. It is
abstract and therefore only derivatives of it MAY appear in an
XML instance. Its purpose is to provide a means for the
definition of authentication more complex than an identifier and
password (i.e. XML PKI ).
o <styleSheet> - as defined this elements contents are a URI. The
URI MUST resolve to an XSL[5] stylesheet.
3.2 Namespace Identifier Requirements
The namespace identifier for a directory namespace and the XML
namespace identifier used by the XML Schema describing the directory
MUST be the same. These namespace identifiers MUST be restricted to
any valid URN[7].
Newton Expires August 23, 2001 [Page 10]
Internet-Draft eXtensible Directory Access Protocol February 2001
This is a restriction on XML_NS[2], which specifies a namespace
identifier is any valid URI[6].
3.3 Names of Entities
The names of entities in a directory namespace MUST be of type CDATA
defined by [3]. They may not contain XML markup. Their use SHOULD
be transcribable.
Names of entities SHOULD be unique within an instance of a directory
namespace. Two entities SHOULD NOT have the same name, but a single
entity MAY be known by multiple names. In situations where a single
name may result in two entities, the directory namespace should make
allowances by defining result types that contain entity references
to both entities (i.e. "foo.com" can refer to both the domain
foo.com and the host foo.com). However, this type of conflict
should generally be avoided.
Newton Expires August 23, 2001 [Page 11]
Internet-Draft eXtensible Directory Access Protocol February 2001
4. URI Requirements
XDAP does not have single URI definition because of the dependencies
on a URI by the mapping between XDAP and a transport protocol.
However, any valid XDAP URI definition MUST meet the following
requirements:
o Using the layout form syntax of RFC2396[6], each XDAP URI MUST
contain a <query> component within its <schema-specific-part>
component. The <query> component MUST be composed of the
directory namespace identifier, a '/' (slash) character, and the
name of an entity within the directory namespace . The layout
form syntax of the <query> component MUST be:
<directory-namespace>/<entity-name>
o The URI MUST be an absolute URI, therefore the scheme component
is always present.
o The URI MUST contain the <query> URI component as defined above.
This component MUST contain the <directory-namespace> component
and the <entity-name> component and therefore MUST always be an
entity reference.
o Each transport mapping MUST define a scheme name. The scheme
name MAY NOT be used other XDAP transport mappings.
There is no default URI scheme or transport mapping.
Newton Expires August 23, 2001 [Page 12]
Internet-Draft eXtensible Directory Access Protocol February 2001
5. Formal XML Syntax
XDAP is specified in XML Schema notation. The formal syntax
presented here is a complete schema representation of XDAP suitable
for automated validation of XDAP XML instances.
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema"
xmlns:xdap="urn:iana:xmlns:xdap1"
targetNamespace="urn:iana:xmlns:xdap1"
elementFormDefault="qualified" >
<annotation>
<documentation>
eXtensible Directory Access Protocol (XDAP) Schema v1
</documentation>
</annotation>
<element name="xdap">
<complexType>
<sequence>
<element name="request"
type="xdap:requestType"
minOccurs="0" maxOccurs="1" />
<element name="response"
type="xdap:responseType"
minOccurs="0" maxOccurs="1" />
</sequence>
</complexType>
</element>
<complexType name="requestType">
<sequence>
<element name="authenticate"
type="xdap:authenticateType"
minOccurs="0" maxOccurs="1" />
<element name="sessionInquiry"
type="xdap:sessionInquiryType"
minOccurs="0" maxOccurs="1" />
<element name="serviceInquiry"
type="xdap:serviceInquiryType"
minOccurs="0" maxOccurs="1" />
<element name="directorySearch"
type="xdap:directorySearchType"
minOccurs="0" maxOccurs="unbounded" />
<element name="quit"
type="xdap:quitType"
minOccurs="0" maxOccurs="1" />
Newton Expires August 23, 2001 [Page 13]
Internet-Draft eXtensible Directory Access Protocol February 2001
</sequence>
<attribute name="sessionToken"
type="string"
use="optional" />
</complexType>
<complexType name="authenticateType">
<choice minOccurs="1" maxOccurs="unbounded">
<element name="simpleAuthentication"
type="xdap:simpleAuthenticationType" />
<element ref="xdap:complexAuthentication" />
</choice>
</complexType>
<complexType name="simpleAuthenticationType">
<sequence>
<element name="authenticationId"
type="string"
minOccurs="1" maxOccurs="1" />
<element name="authenticationPassword"
type="string"
minOccurs="1" maxOccurs="1" />
</sequence>
<attribute name="directoryNamespace"
type="uriReference" use="required" />
</complexType>
<complexType name="complexAuthenticationType">
<attribute name="directoryNamespace"
type="uriReference" use="required" />
</complexType>
<element name="complexAuthentication"
type="xdap:complexAuthenticationType"
abstract="true" />
<complexType name="sessionInquiryType" />
<complexType name="serviceInquiryType" />
<complexType name="directorySearchType" >
<choice>
<element name="lookupEntity"
type="xdap:lookupEntityType" />
<element ref="xdap:query"
minOccurs="1" maxOccurs="unbounded" />
</choice>
</complexType>
Newton Expires August 23, 2001 [Page 14]
Internet-Draft eXtensible Directory Access Protocol February 2001
<complexType name="queryType"/>
<element name="query"
type="xdap:queryType"
abstract="true" />
<complexType name="lookupEntityType" >
<simpleContent>
<extension base="string">
<attribute name="directoryNamespace"
type="uriReference"
use="required" />
</extension>
</simpleContent>
</complexType>
<complexType name="quitType" />
<complexType name="responseType">
<sequence>
<element name="sessionStatus"
type="xdap:sessionStatusType"
minOccurs="0" maxOccurs="1" />
<element name="serviceResult"
type="xdap:serviceResultType"
minOccurs="0" maxOccurs="1" />
<element name="directoryResult"
type="xdap:directoryResultType"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
<attribute name="sessionToken"
type="string" use="optional" />
</complexType>
<complexType name="sessionStatusType" >
<sequence>
<choice
minOccurs="0" maxOccurs="unbounded" >
<element name="currentlyAuthenticated"
type="xdap:authenticationCodeType" />
<element name="authenticationRequired"
type="xdap:authenticationCodeType" />
<element name="noAuthenticationRequired"
type="xdap:authenticationCodeType" />
</choice>
<element name="communicationProblem"
type="xdap:codeType"
minOccurs="0" maxOccurs="1" />
</sequence>
Newton Expires August 23, 2001 [Page 15]
Internet-Draft eXtensible Directory Access Protocol February 2001
</complexType>
<complexType name="codeType">
<all minOccurs="0" maxOccurs="1">
<element name="explanation" type="string" />
<element name="language" type="language" />
</all>
</complexType>
<complexType name="authenticationCodeType">
<all minOccurs="0" maxOccurs="1">
<element name="explanation" type="string" />
<element name="language" type="language" />
</all>
<attribute name="directoryNamespace"
type="uriReference" use="required" />
</complexType>
<complexType name="serviceResultType" >
<sequence>
<element name="directoryNamespace"
minOccurs="1" maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension base="uriReference">
<attribute name="location" type="uriReference"
use="required" />
</extension>
</simpleContent>
</complexType>
</element>
<!--
<element name="directoryNamespace"
type="uriReference"
minOccurs="1" maxOccurs="unbounded" />
-->
</sequence>
</complexType>
<complexType name="directoryResultType" >
<choice minOccurs="0" maxOccurs="unbounded">
<element ref="xdap:result" />
<element name="entityReference"
type="uriReference" />
<element name="searchContinuation"
type="xdap:searchContinuationType" />
<element name="insufficientResources"
type="xdap:codeType" />
<element name="invalidName"
Newton Expires August 23, 2001 [Page 16]
Internet-Draft eXtensible Directory Access Protocol February 2001
type="xdap:codeType" />
<element name="invalidSearch"
type="xdap:codeType" />
<element name="limitExceeded"
type="xdap:codeType" />
<element name="nameNotFound"
type="xdap:codeType" />
<element name="permissionDenied"
type="xdap:codeType" />
<element name="invalidXML"
type="xdap:codeType" />
<element ref="xdap:genericCode" />
</choice>
</complexType>
<complexType name="resultType" />
<element name="result"
type="xdap:resultType"
abstract="true" />
<complexType name="searchContinuationType">
<sequence>
<element ref="xdap:hostReference"
minOccurs="1" maxOccurs="1" />
<element name="directorySearch"
type="xdap:directorySearchType"
minOccurs="1" maxOccurs="1"/>
</sequence>
</complexType>
<complexType name="hostReferenceType">
<sequence>
<element name="scheme" type="string"
minOccurs="1" maxOccurs="1" />
<element name="host" type="string"
minOccurs="1" maxOccurs="1" />
<element name="port" type="positiveInteger"
minOccurs="1" maxOccurs="1" />
</sequence>
</complexType>
<element name="hostReference"
type="xdap:hostReferenceType" />
<element name="genericCode" type="xdap:codeType"
abstract="true" />
<complexType name="stylesheetType" >
Newton Expires August 23, 2001 [Page 17]
Internet-Draft eXtensible Directory Access Protocol February 2001
<attribute name="location"
type="uriReference" use="required" />
</complexType>
<element name="stylesheet"
type="xdap:stylesheetType"
abstract="true" />
</schema>
Newton Expires August 23, 2001 [Page 18]
Internet-Draft eXtensible Directory Access Protocol February 2001
6. Internationalization Considerations
XDAP is represented in XML, which provides native support for
encoding information using the double-byte Unicode character set and
its more compact representations including UTF-8. Compliant XML
processors are required to understand both UTF-8 and raw Unicode
character sets; XML also includes a provision for identifying other
character sets through use of an "encoding" attribute in an <?xml?>
processing instruction. The complete list of character set encoding
identifiers is maintained by IANA and is described in [12] and [8].
Newton Expires August 23, 2001 [Page 19]
Internet-Draft eXtensible Directory Access Protocol February 2001
7. IANA Considerations
XML schemas require a URI for unique identification. Schemas MUST
be registered to ensure URI uniqueness, but the IETF does not
currently have a recommended repository for the registration of XML
schemas. This document uses URNs to describe XML namespaces and XML
schemas. IANA SHOULD maintain a registry of XML namespace and schema
URI assignments. Per policies described in [9], URI assignment
requests SHOULD be reviewed by a designated expert, and values
SHOULD be assigned only as a result of standards action taken by the
IESG.
Newton Expires August 23, 2001 [Page 20]
Internet-Draft eXtensible Directory Access Protocol February 2001
8. Security Considerations
XDAP provides only a simple client authentication mechanism. A
passive attack is sufficient to recover client identifiers and
passwords, allowing trivial session forgery. Protection against
most common attacks should be provided by the underlying transport
protocol or protocols.
The simple client authentication mechanism uses a variant of the
PLAIN SASL mechanism described in [10] to provide a
application-layer authentication capability. Where the PLAIN SASL
mechanism specifies provision of an authorization identifier,
authentication identifier, and password as a single string separated
by ASCII NUL characters, XDAP specifies use of a combined
authorization and authentication identifier and a password provided
as distinct XML elements.
XDAP also allows for the definition of complex authentication
mechanisms in directory namespaces which derive their schemas from
XDAP. The specification for these complex mechanisms MUST describe
all relevant security considerations.
Repeated password guessing attempts can be discouraged by limiting
the number of <authenticate> attempts that can be attempted on an
open session. A server MUST discontinue a session if three
<authenticate> attempts are made with either an invalid client
identifier, an invalid password, or both an invalid client
identifier and an invalid password.
Referral XDAP directory results may contain entity lookups and
search continuations which result in a client query operation
against another directory service. The authentication credentials
used to obtain the directory results SHOULD NOT be used to conduct a
subsequent entity lookup or search continuation.
As specified, XDAP allows a valid XML instance to contain both a
<request> and a <response>. Applications and processes acting only
as a client for a given session MUST issue an
<authenticationRequired> in response to all<authenticate> requests
regardless of the authentication identifier and password.
Applications and processes MAY act in the role of both a client and
server in a session.
Newton Expires August 23, 2001 [Page 21]
Internet-Draft eXtensible Directory Access Protocol February 2001
References
[1] World Wide Web Consortium, "Extensible Markup Language (XML)
1.0", W3C XML, February 1998,
<http://www.w3.org/TR/1998/REC-xml-19980210>.
[2] World Wide Web Consortium, "Namespaces in XML", W3C XML
Namespaces, January 1999,
<http://www.w3.org/TR/1999/REC-xml-names-19990114>.
[3] World Wide Web Consortium, "XML Schema Part 2: Datatypes", W3C
XML Schema, October 2000,
<http://www.w3.org/TR/2000/CR-xmlschema-2-20001024/>.
[4] World Wide Web Consortium, "XML Schema Part 1: Structures",
W3C XML Schema, October 2000,
<http://www.w3.org/TR/2000/CR-xmlschema-1-20001024/>.
[5] World Wide Web Consortium, "Extensible Stylesheet Language
(XSL) Version 1.0", W3C XSL, November 2000,
<http://www.w3.org/TR/2000/CR-xsl-20001121/>.
[6] Berners-Lee, T., Fielding, R.T. and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[7] Moats, R., "URN Syntax", RFC 2141, May 1997.
[8] Reynolds, J. and J. Postel, "ASSIGNED NUMBERS", RFC 1700, STD
2, October 1994.
[9] Narten, T. and H.T. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", RFC 2434, BCP 26,
October 1998.
[10] Newman, C., "Using TLS with IMAP, POP3 and ACAP", RFC 2595,
June 1999.
[11] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, BCP 14, March 1997.
[12] <ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets>
Newton Expires August 23, 2001 [Page 22]
Internet-Draft eXtensible Directory Access Protocol February 2001
Author's Address
Andrew L. Newton
VeriSign, Inc.
505 Huntmar Park Drive
Herndon, VA 20170
USA
Phone: +1 703 948 3382
EMail: anewton@research.netsol.com
URI: http://www.research.netsol.com/
Newton Expires August 23, 2001 [Page 23]
Internet-Draft eXtensible Directory Access Protocol February 2001
Appendix A. Expressing a Base in XDAP
The concept of a base, a specific search or lookup starting point,
is not common to the inherent structure of all directories.
Therefore XDAP does not explicitly define a one. The problem of
expressing a starting point is solved by use of well-known entity
references which return a search continuation. An XDAP URI is an
entity reference and therefore capable of being the base of a
directory.
To illustrate, given the following fictional XDAP URI:
xdap://some.host/urn:iana:xmlns:fooDS/foostart
The client may resolve the URI by issuing a <lookupEntity> request
and the response would be:
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<directoryResult>
<searchContinuation>
<hostReference>
<scheme>xdap</scheme>
<host>some.host</host>
<port>5555</port>
</hostReference>
<directorySearch>
<foo:listFoos
xmlns:foo="urn:iana:xmlns:fooDS"
xsi:schemaLocation="urn:iana:xmlns:fooDS fooDS.xsd" />
<foo:fooTree>foo1:</foo:fooTree>
<foo:filter hidden="true" system="false" />
</foo:listFoos>
</directorySearch>
</searchContinuation>
</directoryResult>
</response>
</xdap>
This mechanism can be used to define both the base of a directory
Newton Expires August 23, 2001 [Page 24]
Internet-Draft eXtensible Directory Access Protocol February 2001
namespace or a directory instance. When the search continuation
contains a host reference to the same host of the directory instance
to which the entity lookup was conducted, this can be considered a
base of a directory instance. If the host reference is to a
different host, this can be considered a base of a directory
namespace.
This document makes no specification or assumptions about roots,
search bases, or entity meshes.
Newton Expires August 23, 2001 [Page 25]
Internet-Draft eXtensible Directory Access Protocol February 2001
Appendix B. Schema Discovery
This specification does not provide a direct mechanism for schema
discovery. However, a method is available.
A client may use the schema location URI of the <xsi:schemaLocation>
element (the second URI) to retrieve the XML Schema document of an
unknown directory namespace (assuming the network resources are
available). This document contains valid XML which may be used by
the client to determine the structure of the unknown directory
namespace. A distinction for the proper use and placement of the
elements inside XDAP requests and responses may be obtained by
evaluating the base types derived from the XDAP schema. XML schema
type libraries should be employed to better facilitate the
understanding of common data types.
In addition, a directory namespace may define query and result
derivatives especially designed for schema discovery within its area
and specific to its needs.
Newton Expires August 23, 2001 [Page 26]
Internet-Draft eXtensible Directory Access Protocol February 2001
Appendix C. An Example Directory Namespace
The following is an example of an XDAP directory for part numbers.
The XML instances are the exchange between the client and server.
C.1 Part Number Schema
This is the formal XML Schema syntax for a mythical directory
application known as urn:iana:xmlns:partno1.
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema"
xmlns:partno="urn:iana:xmlns:partno1"
xmlns:xdap="urn:iana:xmlns:xdap1"
targetNamespace="urn:iana:xmlns:partno1"
elementFormDefault="qualified" >
<annotation>
<documentation>
Part number directory schema conformant to XDAP schema
</documentation>
</annotation>
<complexType name="lookupPartType">
<complexContent>
<extension base="xdap:queryType">
<attribute name="partno"
type="string" use="required" />
</extension>
</complexContent>
</complexType>
<element name="lookupPart" type="partno:lookupPartType"
substitutionGroup="xdap:query" />
<complexType name="listPartsByCategoryType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="categoryId" type="string"
minOccurs="1" maxOccurs="10" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="listPartsByCategory"
type="partno:listPartsByCategoryType"
substitutionGroup="xdap:query" />
Newton Expires August 23, 2001 [Page 27]
Internet-Draft eXtensible Directory Access Protocol February 2001
<element name="listCategories" type="xdap:queryType"
substitutionGroup="xdap:query" />
<complexType name="partType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="name" type="string" />
<element name="description" type="string" />
<element name="partNumber" type="string" />
<element name="categoryId" type="string" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="part" type="partno:partType"
substitutionGroup="xdap:result" />
<complexType name="categoryType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="categoryName" type="string" />
<element name="categoryId" type="string" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="category" type="partno:categoryType"
substitutionGroup="xdap:result" />
<complexType name="stylesheetType" >
<complexContent>
<extension base="xdap:stylesheetType">
<attribute name="location"
type="uriReference" use="fixed"
value="http://www.example.com/partno.xsl" />
</extension>
</complexContent>
</complexType>
<element name="stylesheet"
type="partno:stylesheetType"
substitutionGroup="xdap:stylesheet" />
</schema>
Newton Expires August 23, 2001 [Page 28]
Internet-Draft eXtensible Directory Access Protocol February 2001
C.2 Example Login
This XML instance is a request to authenticate.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<request>
<authenticate>
<simpleAuthentication
directoryNamespace="urn:iana:xmlns:partno1" >
<authenticationId>
bjansen
</authenticationId>
<authenticationPassword>
fly7crow1
</authenticationPassword>
</simpleAuthentication>
</authenticate>
</request>
</xdap>
This XML instance is a response from Figure 7.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<sessionStatus>
<currentlyAuthenticated
directoryNamespace="urn:iana:xmlns:partno1" />
</sessionStatus>
</response>
</xdap>
C.3 Example Service Inquiry
Newton Expires August 23, 2001 [Page 29]
Internet-Draft eXtensible Directory Access Protocol February 2001
This instance is a service inquiry request.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<request>
<serviceInquiry />
</request>
</xdap>
This XML instance is a response to Figure 9.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<serviceResult>
<directoryNamespace
location="ftp://ftp.isi.edu/iana/urn/xmlns/partno1.xsd">
urn:iana:xmlns:partno1
</directoryNamespace>
<directoryNamespace
location="ftp://ftp.isi.edu/iana/urn/xmlns/foo1.xsd">
urn:iana:xmlns:foo1
</directoryNamespace>
</serviceResult>
</response>
</xdap>
C.4 Example Search
Newton Expires August 23, 2001 [Page 30]
Internet-Draft eXtensible Directory Access Protocol February 2001
This XML instance demonstrates a directory search request to look up
a part number.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<request>
<directorySearch>
<partno:lookupPart
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd"
partno="5656573-3993A" />
</directorySearch>
</request>
</xdap>
This instance is the response sent in reply to Figure 11. It
demonstrates a simple directory result.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<directoryResult>
<partno:part
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" >
<partno:name>Wacky Widget</partno:name>
<partno:description>
Wonko World's Wonderful Wacky Widget
</partno:description>
<partno:partNumber>5656573-3993A</partno:partNumber>
<partno:categoryId>29</partno:categoryId>
</partno:part>
</directoryResult>
</response>
</xdap>
Newton Expires August 23, 2001 [Page 31]
Internet-Draft eXtensible Directory Access Protocol February 2001
C.5 Another Example Search
This instance is a request to list all the part number categories.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<request>
<directorySearch>
<partno:listCategories
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" />
</directorySearch>
</request>
</xdap>
This is the response to Figure 14. It demonstrates a more complex
result set consisting of entities in the queried directory, entity
references located elsewhere, and search continuations for other
directories.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<directoryResult>
<partno:category
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" >
<partno:categoryName>Generic Widgets</partno:categoryName>
<partno:categoryId>29</partno:categoryId>
</partno:category>
<partno:category
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" >
<partno:categoryName>Wacky Widgets</partno:categoryName>
<partno:categoryId>30</partno:categoryId>
</partno:category>
<partno:category
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" >
<partno:categoryName>Wild Widgets</partno:categoryName>
Newton Expires August 23, 2001 [Page 32]
Internet-Draft eXtensible Directory Access Protocol February 2001
<partno:categoryId>31</partno:categoryId>
</partno:category>
<entityReference>
xdap://localhost:8676/urn:iana:xmlns:partno1?/categoryId/32
</entityReference>
<entityReference>
xdap://localhost:8676/urn:iana:xmlns:partno1?/categoryId/33
</entityReference>
<entityReference>
xdap://localhost:8676/urn:iana:xmlns:partno1?/categoryId/34
</entityReference>
<searchContinuation>
<hostReference>
<scheme>xdap</scheme>
<host>localhost</host>
<port>3933</port>
</hostReference>
<directorySearch>
<partno:listCategories
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" />
</directorySearch>
</searchContinuation>
</directoryResult>
</response>
</xdap>
C.6 Example Entity Lookup
Newton Expires August 23, 2001 [Page 33]
Internet-Draft eXtensible Directory Access Protocol February 2001
This instance is an entity lookup request. Notice that it is the
logical continuation from one of the entity references in Figure 14
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<request>
<directorySearch>
<lookupEntity
directoryNamespace="urn:iana:xmlns:partno1"
>/category/32</lookupEntity>
</directorySearch>
</request>
</xdap>
This instance is the response to Figure 15.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<directoryResult>
<searchContinuation>
<hostReference>
<scheme>xdap</scheme>
<host>localhost</host>
<port>5555</port>
</hostReference>
<directorySearch>
<partno:listCategories
xmlns:partno="urn:iana:xmlns:partno1"
xsi:schemaLocation="urn:iana:xmlns:partno1 partno.xsd" />
</directorySearch>
</searchContinuation>
</directoryResult>
</response>
</xdap>
Newton Expires August 23, 2001 [Page 34]
Internet-Draft eXtensible Directory Access Protocol February 2001
Appendix D. Document Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC2119[11].
Newton Expires August 23, 2001 [Page 35]
Internet-Draft eXtensible Directory Access Protocol February 2001
Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC editor function is currently provided by the
Internet Society.
Newton Expires August 23, 2001 [Page 36]
Network Working Group A.L. Newton
Internet-Draft VeriSign, Inc.
Expires: August 23, 2001 February 22, 2001
XDAP Domain Directory Schema
draft-newton-xdap-domdir-00
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 23, 2001.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract
This document describes an XDAP directory namespace and schema for
registered DNS information. The schema extends the necessary query
and result operations of XDAP to provide a functional equivalent of
the whois command syntaxes and results often used by domain
registries and registrars.
Newton Expires August 23, 2001 [Page 1]
Internet-Draft XDAP Domain Directory Schema February 2001
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Document Terminology . . . . . . . . . . . . . . . . . . . . 4
3. Schema Description . . . . . . . . . . . . . . . . . . . . . 5
3.1 Query Derivatives . . . . . . . . . . . . . . . . . . . . . 5
3.1.1 <lookupDomain> Query . . . . . . . . . . . . . . . . . . . . 5
3.1.2 <listSponsors> Query . . . . . . . . . . . . . . . . . . . . 5
3.1.3 <findDomainByHolder> Query . . . . . . . . . . . . . . . . . 5
3.1.4 <findDomainByName> Query . . . . . . . . . . . . . . . . . . 5
3.1.5 <lookupContact> Query . . . . . . . . . . . . . . . . . . . 5
3.1.6 <findContacts> Query . . . . . . . . . . . . . . . . . . . . 6
3.1.7 <lookupHost> Query . . . . . . . . . . . . . . . . . . . . . 6
3.1.8 <findHostsByDomain> Query . . . . . . . . . . . . . . . . . 6
3.2 Result Derivatives . . . . . . . . . . . . . . . . . . . . . 6
3.2.1 <domain> Result . . . . . . . . . . . . . . . . . . . . . . 6
3.2.2 <domains> Result . . . . . . . . . . . . . . . . . . . . . . 7
3.2.3 <sponsors> Result . . . . . . . . . . . . . . . . . . . . . 7
3.2.4 <hostInfo> Result . . . . . . . . . . . . . . . . . . . . . 7
3.2.5 <hosts> Result . . . . . . . . . . . . . . . . . . . . . . . 7
3.2.6 <contactInfo> Result . . . . . . . . . . . . . . . . . . . . 7
3.2.7 <contacts> Result . . . . . . . . . . . . . . . . . . . . . 8
3.3 Global Types . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4 Support for <xdap:lookupEntity> . . . . . . . . . . . . . . 8
4. Formal XML Syntax . . . . . . . . . . . . . . . . . . . . . 9
5. Internationalization Considerations . . . . . . . . . . . . 19
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . 20
7. Security Considerations . . . . . . . . . . . . . . . . . . 21
References . . . . . . . . . . . . . . . . . . . . . . . . . 22
Author's Address . . . . . . . . . . . . . . . . . . . . . . 22
A. An Example Request and Response . . . . . . . . . . . . . . 23
Full Copyright Statement . . . . . . . . . . . . . . . . . . 25
Newton Expires August 23, 2001 [Page 2]
Internet-Draft XDAP Domain Directory Schema February 2001
1. Introduction
This document describes an Internet address directory using an XML
Schema[4] derived from and using the XDAP[5] schema. The query and
result types are similar in function to the whois commands and
results often used by domain registries/registrars today.
The schema given is this document is specified using the Extensible
Markup Language (XML) 1.0 as described in [1], XML Schema notation
as described in [3] and [4], and XML Namespaces as described in [2].
It is important to note that XML is case sensitive. XML
specifications and examples provided in this document MUST be
interpreted in the exact character case presented to develop a
conforming implementation.
Newton Expires August 23, 2001 [Page 3]
Internet-Draft XDAP Domain Directory Schema February 2001
2. Document Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC2119[9].
The terms "holder" and sponsor" are taken from the meaning described
in [6].
Newton Expires August 23, 2001 [Page 4]
Internet-Draft XDAP Domain Directory Schema February 2001
3. Schema Description
The schema for this directory namespace defines no
<complexAuthentication> derivative. Applications of this namespace
should rely on either the XDAP transport or <simpleAuthentication>
for client authentication.
XDAP requires the derivation of both query and result elements by a
directory namespace. These descriptions follow.
3.1 Query Derivatives
3.1.1 <lookupDomain> Query
This query does a domain lookup. This lookup is specified either
with a handle for the domain or the name of the domain as it would
be used in DNS.
3.1.2 <listSponsors> Query
This query returns continuation searches in the directory services
of the "down-stream" sponsors of a directory. A search constraint of
<base> MAY restrict the list to sponsors only of a particular
domain.
3.1.3 <findDomainByHolder> Query
<findDomainByHolder> finds a domain entity by the common name of the
domain's holder. A search constraint of <base> MAY restrict the
results to domains only underneath the domain specified by its
content. The <beginsWith> element MUST be present and specifies the
beginning of the common name of the holder. The <endsWith> element
is OPTIONAL and MUST contain the end of the common name of the
holder.
3.1.4 <findDomainByName> Query
Similar to <findDomainByHolder>, <findDomainByHolder> finds a domain
entity by the name of the domain as it is known it DNS. A search
constraint of <base> MAY restrict the results to domains only
underneath the domain specified by its content. The <beginsWith>
element MUST be present and specifies the beginning of the domain
name. The <endsWith> element is OPTIONAL and MUST contain the end of
the domain name.
3.1.5 <lookupContact> Query
This query does a contact lookup. The lookup is specified with the
handle of the contact.
Newton Expires August 23, 2001 [Page 5]
Internet-Draft XDAP Domain Directory Schema February 2001
3.1.6 <findContacts> Query
<findContacts> searches for contacts given search constraints. The
<beginsWith> element MUST be present and specifies the beginning of
the common name of the contact. The <endsWith> element is OPTIONAL
and MUST contain the end of the common name of the contact.
The <type> element is OPTIONAL and SHOULD contain a recognized type
of contact. Typically the values for this element denote
multiplicity of the contact, such as "organization" or "person".
3.1.7 <lookupHost> Query
This is a simple named look up of a name server host. The host MUST
be specified by one of the following elements:
o <handle> - a registry assigned unique identifier.
o <hostName> - the fully-qualified name of the host.
o <ipV4Address> - the IP version 4 address of the host.
o <ipV6Address> - the IP version 6 address of the host.
3.1.8 <findHostsByDomain> Query
This query does a simple search for the name servers hosting a
domain. The search constraint <domainName> MUST be present.
3.2 Result Derivatives
3.2.1 <domain> Result
This is the expected result of a <lookupDomain> query. The children
of the <domain> element are as follows:
o <domainName> - the full name of the domain as it is in DNS. This
element MUST be present.
o <domainReference> - an entity reference to a domain entry in
another directory service representing this same domain entity.
This reference SHOULD be to the domain entry in a sponsor's
directory service. The element is OPTIONAL.
o <nameServerReference> - an entity reference to an authoritative
name server for this domain. This element is OPTIONAL and MAY
repeat as many times as necessary.
o <holder> - an element representing the holder of the domain. The
Newton Expires August 23, 2001 [Page 6]
Internet-Draft XDAP Domain Directory Schema February 2001
children of this element contain the contact information of the
holder and MUST be identical in specification as the children of
<contactInfo>. This element is OPTIONAL.
o <contactReference> - specifies a reference to a contact of the
domain. The first child of this element MUST be
<entityReference> and contain a reference to the contact. The
second element, <role>, specifies the relationship between the
contact and the domain. Usually, the contents of this element
are "technical", "billing", or "administrative". This element is
OPTIONAL and MAY repeat as many times as necessary.
3.2.2 <domains> Result
This is the expected result of a <findDomainByName> or
<findDomainByHolder> query. It MAY be empty, but if it has
children, they MUST be <domain> elements.
3.2.3 <sponsors> Result
This element is the expected result of a <listSponsors> query. The
children of this element are <searchContinuation> as specified by
XDAP.
3.2.4 <hostInfo> Result
The <hostInfo> element is the expected result of a <lookupHost>
query. It contains elements for the fully qualified host name of
the host, the IP address of the host, and a reference to the host
contact.
The address elements contain the IP address of the name server,
either IP v4 or IP v6, and an OPTIONAL reference to the network
which contains the given address.
3.2.5 <hosts> Result
This is the expected result of <findHostsByDomain> query. It MAY be
empty, but if it has children, they MUST be <host> elements.
3.2.6 <contactInfo> Result
The <contactInfo> element is the expected result of a
<lookupContact> query. The children that MUST be present are
<handle>, containing a registry assigned unique identifier, and
<commonName>, which holds the common name of the contact. The other
children of this element are OPTIONAL and contain Internet, phone,
and postal address information.
Newton Expires August 23, 2001 [Page 7]
Internet-Draft XDAP Domain Directory Schema February 2001
3.2.7 <contacts> Result
The <contacts> element is the expected result of a <findContacts>
query. This element MAY have no children; if it is not empty the
children MUST be <contactInfo> elements.
3.3 Global Types
Some of the global types defined by the schema specified in this
document are expressed using regular expressions. The regular
expressions used for these definitions do not fully represent every
allowable syntax for the intended type, but meet a standard of
reasonableness for the expression of the types.
3.4 Support for <xdap:lookupEntity>
The following types of named entities are recognized by the
<lookupEntity> query of XDAP:
o handles - unique identifiers assigned the domain
registry/registrar. These handles are defined to have their type
as the first part of the handle. A query with a type "host" will
yield a <hostInfo> result. A query with a type "domain" will
yield a <domain> result. The other types, "org", "person", and
"role" will yield a <contactInfo> result.
o host names and domain names - the fully qualified host name of a
name server or the fully qualified name of a domain. Queries
with a host name will yield a <hostInfo> result, and queries with
a domain name will yield a <domain> result. In the unlikely and
rare case where a name server and a host name may be the same, a
query will result in a <hostOrDomain> element. This element
contains entity references to both the name server host entry and
the domain entry known by that name.
o IP addresses - the address, either IP v4 or IP v6, of a name
server. A query with an IP address will yield a result of
<hostInfo>.
Newton Expires August 23, 2001 [Page 8]
Internet-Draft XDAP Domain Directory Schema February 2001
4. Formal XML Syntax
This domain directory is specified in the XML Schema notation. The
formal syntax presented here is a complete schema representation
suitable for automated validation of an XML instance when combined
with the formal schema syntax of XDAP. Due to document formatting
restrictions, readers should note that the regular expressions
expressed in this schema DO NOT contain whitespace within the quotes
containing the regular expression.
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema"
xmlns:domdir="urn:iana:xmlns:domdir1"
xmlns:xdap="urn:iana:xmlns:xdap1"
targetNamespace="urn:iana:xmlns:domdir1"
elementFormDefault="qualified" >
<annotation>
<documentation>
Domain directory schema
derived from XDAP schema
</documentation>
</annotation>
<!-- -->
<!-- Query types -->
<!-- -->
<complexType name="lookupDomainType">
<complexContent>
<extension base="xdap:queryType">
<choice>
<element name="handle"
type="domdir:handleType" />
<element name="domainName"
type="domdir:domainNameType" />
</choice>
</extension>
</complexContent>
</complexType>
<element name="lookupDomain"
type="domdir:lookupDomainType"
substitutionGroup="xdap:query" />
<complexType name="listSponsorsType">
<complexContent>
<extension base="xdap:queryType">
Newton Expires August 23, 2001 [Page 9]
Internet-Draft XDAP Domain Directory Schema February 2001
<sequence>
<element name="base"
type="domdir:domainNameType"
minOccurs="0" maxOccurs="1" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="listSponsors"
type="domdir:listSponsorsType"
substitutionGroup="xdap:query" />
<complexType name="findDomainByHolderType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="base"
type="domdir:domainNameType"
minOccurs="0" maxOccurs="1" />
<element name="beginsWith"
type="CDATA" minLength="3"
minOccurs="1" maxOccurs="1" />
<element name="endsWith"
type="CDATA" minLength="2"
minOccurs="0" maxOccurs="1" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="findDomainByHolder"
type="domdir:findDomainByHolderType"
substitutionGroup="xdap:query" />
<complexType name="findDomainByNameType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="base"
type="domdir:domainNameType"
minOccurs="0" maxOccurs="1" />
<element name="beginsWith"
type="CDATA" minLength="3"
minOccurs="1" maxOccurs="1" />
<element name="endsWith"
type="CDATA" minLength="2"
minOccurs="0" maxOccurs="1" />
</sequence>
Newton Expires August 23, 2001 [Page 10]
Internet-Draft XDAP Domain Directory Schema February 2001
</extension>
</complexContent>
</complexType>
<element name="findDomainByName"
type="domdir:findDomainByNameType"
substitutionGroup="xdap:query" />
<complexType name="lookupContactType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="handle"
type="domdir:handleType" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="lookupContact"
type="domdir:lookupContactType"
substitutionGroup="xdap:query" />
<complexType name="findContactsType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="beginsWith"
type="CDATA" minLength="3"
minOccurs="1" maxOccurs="1" />
<element name="endsWith"
type="CDATA" minLength="2"
minOccurs="0" maxOccurs="1" />
<element name="type"
type="CDATA"
minOccurs="0" maxOccurs="1" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="findContactsType"
type="domdir:findContactsType"
substitutionGroup="xdap:query" />
<complexType name="lookupHostType">
<complexContent>
<extension base="xdap:queryType">
<choice>
Newton Expires August 23, 2001 [Page 11]
Internet-Draft XDAP Domain Directory Schema February 2001
<element name="handle"
type="domdir:handleType" />
<element name="hostName"
type="domdir:domainNameType" />
<element name="ipV4Address"
type="domdir:dotQuadIPv4Type" />
<element name="ipV6Address"
type="domdir:textIPv6AddressType" />
</choice>
</extension>
</complexContent>
</complexType>
<element name="lookupHost"
type="domdir:lookupHostType"
substitutionGroup="xdap:query" />
<complexType name="findHostsByDomainType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="domainName"
type="domdir:domainNameType" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="findHostsByDomain"
type="domdir:findHostsByDomainType"
substitutionGroup="xdap:query" />
<!-- -->
<!-- Result types -->
<!-- -->
<complexType name="domainType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="domainName"
type="domdir:domainNameType" />
<element name="domainReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
<element name="nameServerReference"
type="uriReference"
minOccurs="0" maxOccurs="unbounded" />
<element name="holder"
Newton Expires August 23, 2001 [Page 12]
Internet-Draft XDAP Domain Directory Schema February 2001
type="domdir:contactInfoType"
minOccurs="0" maxOccurs="1" />
<element name="contactReference"
minOccurs="0" maxOccurs="unbounded" >
<complexType>
<sequence>
<element name="entityReference"
type="uriReference" />
<element name="role"
type="CDATA" />
</sequence>
</complexType>
</element>
</sequence>
</extension>
</complexContent>
</complexType>
<element name="domain"
type="domdir:domainType"
substitutionGroup="xdap:result" />
<complexType name="sponsorsType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="searchContinuation"
type="xdap:searchContinuationType"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="sponsors"
type="domdir:sponsorsType"
substitutionGroup="xdap:result" />
<complexType name="domainsType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="domain"
type="domdir:domainType"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
Newton Expires August 23, 2001 [Page 13]
Internet-Draft XDAP Domain Directory Schema February 2001
<element name="domains"
type="domdir:domainsType"
substitutionGroup="xdap:result" />
<complexType name="hostInfoType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="handle"
type="domdir:handleType"
minOccurs="0" maxOccurs="1" />
<element name="hostName"
type="domdir:domainNameType" />
<choice
minOccurs="1" maxOccurs="unbounded" >
<element name="ipV4">
<complexType>
<sequence>
<element name="ipV4Address"
type="domdir:dotQuadIPv4Type" />
<element name="networkReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
</sequence>
</complexType>
</element>
<element name="ipV6">
<complexType>
<sequence>
<element name="ipV6Address"
type="domdir:textIPv6AddressType" />
<element name="networkReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
</sequence>
</complexType>
</element>
</choice>
<element name="contactReference"
type="uriReference" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="hostInfo"
type="domdir:hostInfoType"
substitutionGroup="xdap:result" />
Newton Expires August 23, 2001 [Page 14]
Internet-Draft XDAP Domain Directory Schema February 2001
<complexType name="hostsType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="host"
type="domdir:hostInfoType"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="hosts"
type="domdir:hostsType"
substitutionGroup="xdap:result" />
<complexType name="contactInfoType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="handle"
type="domdir:handleType" />
<element name="commonName"
type="CDATA" />
<element name="organization"
type="CDATA"
minOccurs="0" maxOccurs="1" />
<element name="e-mail"
type="CDATA"
minOccurs="0" maxOccurs="1" />
<element name="address"
type="string"
minOccurs="0" maxOccurs="1" />
<element name="city"
type="string"
minOccurs="0" maxOccurs="1" />
<element name="region"
type="string"
minOccurs="0" maxOccurs="1" />
<element name="postalCode"
type="CDATA"
minOccurs="0" maxOccurs="1" />
<element name="country"
type="token"
minOccurs="0" maxOccurs="1" />
<element name="phone"
type="CDATA"
minOccurs="0" maxOccurs="1" />
<element name="fax"
Newton Expires August 23, 2001 [Page 15]
Internet-Draft XDAP Domain Directory Schema February 2001
type="CDATA"
minOccurs="0" maxOccurs="1" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="contactInfo"
type="domdir:contactInfoType"
substitutionGroup="xdap:result" />
<complexType name="contactsType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="contact"
type="domdir:contactInfoType"
minOccurs="0" maxOccurs="unbounded" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="contacts"
type="domdir:contactsType"
substitutionGroup="xdap:result" />
<complexType name="hostOrDomainType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="nameServerReference"
type="uriReference" />
<element name="domainReference"
type="uriReference" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="hostOrDomain"
type="domdir:hostOrDomainType"
substitutionGroup="xdap:result" />
<!-- -->
<!-- Global types -->
<!-- -->
<simpleType name="domainNameType">
Newton Expires August 23, 2001 [Page 16]
Internet-Draft XDAP Domain Directory Schema February 2001
<restriction base="CDATA">
<pattern
value="([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]\.)*([a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])?" />
<maxLength value="255" />
</restriction>
</simpleType>
<simpleType name="handleType">
<restriction base="CDATA">
<pattern value="(host|org|person|role|domain):[A-Za-z0-9-]*" />
<maxLength value="255" />
</restriction>
</simpleType>
<simpleType name="dotQuadIPv4Type">
<restriction base="string">
<pattern value="([\Nd]{1,3}.){3}[\Nd]{1,3}" />
<minLength value="7" />
<maxLength value="15" />
</restriction>
</simpleType>
<!-- does not support '::' -->
<simpleType name="textIPv6AddressType">
<restriction base="string">
<pattern value="(([\NdA-F]{1,4}:){7}[\NdA-F]{1,4})(:([\Nd]{1,3}.){3}[\Nd]{1,3})?"/>
<minLength value="16"/>
<maxLength value="39"/>
</restriction>
</simpleType>
<!-- -->
<!-- Other Derived types -->
<!-- -->
<complexType name="stylesheetType" >
<complexContent>
<extension base="xdap:stylesheetType">
<attribute name="location"
type="uriReference" use="fixed"
value="http://www.example.com/partno.xsl" />
</extension>
</complexContent>
</complexType>
<element name="stylesheet"
type="partno:stylesheetType"
substitutionGroup="xdap:stylesheet" />
Newton Expires August 23, 2001 [Page 17]
Internet-Draft XDAP Domain Directory Schema February 2001
</schema>
Newton Expires August 23, 2001 [Page 18]
Internet-Draft XDAP Domain Directory Schema February 2001
5. Internationalization Considerations
The defining schema for this directory namespace is represented in
XML, which provides native support for encoding information using
the double-byte Unicode character set and its more compact
representations including UTF-8. Compliant XML processors are
required to understand both UTF-8 and raw Unicode character sets;
XML also includes a provision for identifying other character sets
through use of an "encoding" attribute in an <?xml?> processing
instruction. The complete list of character set encoding identifiers
is maintained by IANA and is described in [10] and [7].
Newton Expires August 23, 2001 [Page 19]
Internet-Draft XDAP Domain Directory Schema February 2001
6. IANA Considerations
XML schemas require a URI for unique identification. Schemas MUST
be registered to ensure URI uniqueness, but the IETF does not
currently have a recommended repository for the registration of XML
schemas. This document uses URNs to describe XML namespaces and XML
schemas. IANA SHOULD maintain a registry of XML namespace and schema
URI assignments. Per policies described in [8], URI assignment
requests SHOULD be reviewed by a designated expert, and values
SHOULD be assigned only as a result of standards action taken by the
IESG.
Newton Expires August 23, 2001 [Page 20]
Internet-Draft XDAP Domain Directory Schema February 2001
7. Security Considerations
The schema given in this document describes no
<complexAuthentication> derivatives nor specifies any authentication
mechanism beyond that specified by [5].
Newton Expires August 23, 2001 [Page 21]
Internet-Draft XDAP Domain Directory Schema February 2001
References
[1] World Wide Web Consortium, "Extensible Markup Language (XML)
1.0", W3C XML, February 1998,
<http://www.w3.org/TR/1998/REC-xml-19980210>.
[2] World Wide Web Consortium, "Namespaces in XML", W3C XML
Namespaces, January 1999,
<http://www.w3.org/TR/1999/REC-xml-names-19990114>.
[3] World Wide Web Consortium, "XML Schema Part 2: Datatypes", W3C
XML Schema, October 2000,
<http://www.w3.org/TR/2000/CR-xmlschema-2-20001024/>.
[4] World Wide Web Consortium, "XML Schema Part 1: Structures", W3C
XML Schema, October 2000,
<http://www.w3.org/TR/2000/CR-xmlschema-1-20001024/>.
[5] Newton, A., "eXtensible Directory Access Protocol", Internet
Draft, a work in-progress., February 2001.
[6] Rader, R., "Domain Name Whois Data Element and Related
Definitions", Internet Draft, a work in-progress., January 2001.
[7] Reynolds, J. and J. Postel, "ASSIGNED NUMBERS", RFC 1700, STD
2, October 1994.
[8] Narten, T. and H.T. Alvestrand, "Guidelines for Writing an IANA
Considerations Section in RFCs", RFC 2434, BCP 26, October 1998.
[9] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", RFC 2119, BCP 14, March 1997.
[10] <ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets>
Author's Address
Andrew L. Newton
VeriSign, Inc.
505 Huntmar Park Drive
Herndon, VA 20170
USA
Phone: +1 703 948 3382
EMail: anewton@research.netsol.com
URI: http://www.research.netsol.com/
Newton Expires August 23, 2001 [Page 22]
Internet-Draft XDAP Domain Directory Schema February 2001
Appendix A. An Example Request and Response
The following is an example of an XDAP request and response using
this directory namespace.
This XML instance is a request to search for domains by the
holder's name.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<request>
<directorySearch>
<domdir:findDomainByHolder
xmlns:domdir="urn:iana:xmlns:domdir1"
xsi:schemaLocation="urn:iana:xmlns:domdir1 domdir.xsd" >
<domdir:base>com</domdir:base>
<domdir:beginsWith>
The Cobbler Shoppe
</domdir:beginsWith>
</domdir:findDomainByHolder>
</directorySearch>
</request>
</xdap>
This XML instance is a response from Figure 2.
<?xml version="1.0"?>
<xdap xmlns="urn:iana:xmlns:xdap1"
xmlns:xdap="urn:iana:xmlns:xdap1"
xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance"
xsi:schemaLocation="urn:iana:xmlns:xdap1 xdap.xsd" >
<response>
<directoryResult>
<domdir:domains
xmlns="urn:iana:xmlns:domdir1"
xmlns:domdir="urn:iana:xmlns:domdir1"
xsi:schemaLocation="urn:iana:xmlns:domdir1 domdir.xsd" >
<domain>
<domainName>thecobblershoppe.com</domainName>
<nameServerReference>
xdap://a.host/urn:iana:xmlns:domdir1/host:research7-hst
</nameServerReference>
<nameServerReference>
Newton Expires August 23, 2001 [Page 23]
Internet-Draft XDAP Domain Directory Schema February 2001
xdap://a.host/urn:iana:xmlns:domdir1/host:nso1184-hst
</nameServerReference>
<holder>
<handle>person:beb140</handle>
<commonName>
Bill Eckels
</commonName>
<organization>
The Cobbler Shoppe
</organization>
<e-mail>
bille@bjmk.com
</e-mail>
<address>
21 North Main Street
</address>
<city>
Britt
</city>
<region>
IA
</region>
<postalCode>
50423
</postalCode>
<country>
US
</country>
<phone>
515-843-3521
</phone>
</holder>
</domain>
</domdir:domains>
</directoryResult>
</response>
</xdap>
Newton Expires August 23, 2001 [Page 24]
Internet-Draft XDAP Domain Directory Schema February 2001
Full Copyright Statement
Copyright (C) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC editor function is currently provided by the
Internet Society.
Newton Expires August 23, 2001 [Page 25]
Network Working Group A.L. Newton
Internet-Draft VeriSign, Inc.
Expires: August 23, 2001 February 22, 2001
XDAP IP Directory Schema
draft-newton-xdap-ipdir-00
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 23, 2001.
Copyright Notice
Copyright (C) The Internet Society (2001). All Rights Reserved.
Abstract
This document describes an XDAP directory namespace and schema for
registered Internet address information. The schema extends the
necessary query and result operations of XDAP to provide a
functional equivalent of the whois command syntaxes and results
often used by IP registries.
Newton Expires August 23, 2001 [Page 1]
Internet-Draft XDAP IP Directory Schema February 2001
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Document Terminology . . . . . . . . . . . . . . . . . . . . 4
3. Schema Description . . . . . . . . . . . . . . . . . . . . . 5
3.1 Query Derivatives . . . . . . . . . . . . . . . . . . . . . 5
3.1.1 <lookupContact> Query . . . . . . . . . . . . . . . . . . . 5
3.1.2 <findContacts> Query . . . . . . . . . . . . . . . . . . . . 5
3.1.3 <lookupHost> Query . . . . . . . . . . . . . . . . . . . . . 5
3.1.4 <lookupNetwork> Query . . . . . . . . . . . . . . . . . . . 5
3.1.5 <lookupAutonomousSystem> Query . . . . . . . . . . . . . . . 6
3.2 Result Derivatives . . . . . . . . . . . . . . . . . . . . . 6
3.2.1 <hostInfo> Result . . . . . . . . . . . . . . . . . . . . . 6
3.2.2 <networkInfo> Result . . . . . . . . . . . . . . . . . . . . 6
3.2.3 <autonomousSystemInfo> Result . . . . . . . . . . . . . . . 6
3.2.4 <contactInfo> Result . . . . . . . . . . . . . . . . . . . . 7
3.2.5 <contacts> Result . . . . . . . . . . . . . . . . . . . . . 7
3.3 Global Types . . . . . . . . . . . . . . . . . . . . . . . . 7
3.4 Support for <xdap:lookupEntity> . . . . . . . . . . . . . . 7
4. Formal XML Syntax . . . . . . . . . . . . . . . . . . . . . 9
5. Internationalization Considerations . . . . . . . . . . . . 17
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . 18
7. Security Considerations . . . . . . . . . . . . . . . . . . 19
References . . . . . . . . . . . . . . . . . . . . . . . . . 20
Author's Address . . . . . . . . . . . . . . . . . . . . . . 20
A. An Example Request and Response . . . . . . . . . . . . . . 21
Full Copyright Statement . . . . . . . . . . . . . . . . . . 23
Newton Expires August 23, 2001 [Page 2]
Internet-Draft XDAP IP Directory Schema February 2001
1. Introduction
This document describes an Internet address directory using an XML
Schema[4] derived from and using the XDAP[5] schema. The query and
result types are similar in function to the whois commands and
results often used by IP address registries today.
The schema given is this document is specified using the Extensible
Markup Language (XML) 1.0 as described in [1], XML Schema notation
as described in [3] and [4], and XML Namespaces as described in [2].
It is important to note that XML is case sensitive. XML
specifications and examples provided in this document MUST be
interpreted in the exact character case presented to develop a
conforming implementation.
Newton Expires August 23, 2001 [Page 3]
Internet-Draft XDAP IP Directory Schema February 2001
2. Document Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC2119[9].
The term "holder" is taken from the meaning described in [6].
However, the term as it is used in this document refers to an
individual or organization with the right to use an IP network and
not a domain name.
Newton Expires August 23, 2001 [Page 4]
Internet-Draft XDAP IP Directory Schema February 2001
3. Schema Description
The schema for this directory namespace defines no
<complexAuthentication> derivative. Applications of this namespace
should rely on either the XDAP transport or <simpleAuthentication>
for client authentication.
XDAP requires the derivation of both query and result elements by a
directory namespace. These descriptions follow.
3.1 Query Derivatives
3.1.1 <lookupContact> Query
This is a simple named look up of a single contact. The contact is
specified by the <handle> element.
3.1.2 <findContacts> Query
<findContacts> searches for contacts given search constraints. The
<beginsWith> element MUST be present and specifies the beginning of
the common name of the contact. The <endsWith> element is OPTIONAL
and MUST contain the end of the common name of the contact.
The <type> element is OPTIONAL and SHOULD contain a recognized type
of contact. Typically the values for this element denote
multiplicity of the contact, such as "organization" or "person".
3.1.3 <lookupHost> Query
This is a simple named look up of a name server host. The host MUST
be specified by one of the following elements:
o <handle> - a registry assigned unique identifier.
o <hostName> - the fully-qualified name of the host.
o <ipV4Address> - the IP version 4 address of the host.
o <ipV6Address> - the IP version 6 address of the host.
3.1.4 <lookupNetwork> Query
This is a simple named look up of an IP network. The network MUST be
specified by one of the following elements:
o <ipV4Address> - the IP version 4 network address of the network.
o <ipV6Address> - the IP version 6 network address of the network.
Newton Expires August 23, 2001 [Page 5]
Internet-Draft XDAP IP Directory Schema February 2001
3.1.5 <lookupAutonomousSystem> Query
This is a simple named look up of an autonomous system. The system
MUST be specified by one of the following elements:
o <handle> - a registry assigned unique identifier.
o <number> - the autonomous system number.
3.2 Result Derivatives
3.2.1 <hostInfo> Result
The <hostInfo> element is the expected result of a <lookupHost>
query. It contains elements for the fully qualified host name of
the host, the IP address of the host, and a reference to the host
contact.
The address elements contain the IP address of the name server,
either IP v4 or IP v6, and an OPTIONAL reference to the network
which contains the given address.
3.2.2 <networkInfo> Result
The <networkInfo> element is the expected result of a
<lookupNetwork> query. It has the following child elements:
o <holderReference> is an entity reference to the holder of the
network. This element is OPTIONAL.
o <contactReference> is an entity reference to the technical
contact of the network. The element is OPTIONAL.
o Either <ipV4> or <ipV6> MUST be present. Each element contains
children representing the start and end of the network in the
appropriate format.
3.2.3 <autonomousSystemInfo> Result
The <autonomousSystemInfo> element is the expected result of a
<lookupAutonomousSystem> query. It has the following children:
o <holderReference> is an entity reference to the holder of the
autonomous system. This is an OPTIONAL element.
o <contactReference> is an entity reference to the technical
contact of the autonomous system. This is an OPTIONAL element.
o <handle> is a registry assigned unique identifier. This element
Newton Expires August 23, 2001 [Page 6]
Internet-Draft XDAP IP Directory Schema February 2001
MUST be present.
o <startNumber> is a positive integer representing the starting
number of the autonomous system. This element MUST be present.
o <endNumber> is a positive integer representing the final number
of the autonomous system. This element MUST be present.
3.2.4 <contactInfo> Result
The <contactInfo> element is the expected result of a
<lookupContact> query. The children that MUST be present are
<handle>, containing a registry assigned unique identifier, and
<commonName>, which holds the common name of the contact. The other
children of this element are OPTIONAL and contain Internet, phone,
and postal address information.
3.2.5 <contacts> Result
The <contacts> element is the expected result of a <findContacts>
query. This element MAY have no children, if it is not empty the
children MUST be <contactInfo> elements.
3.3 Global Types
Some of the global types defined by the schema specified in this
document are expressed using regular expressions. The regular
expressions used for these definitions do not fully represent every
allowable syntax for the intended type, but meet a standard of
reasonableness for the expression of the types.
3.4 Support for <xdap:lookupEntity>
The following types of named entities are recognized by the
<lookupEntity> query of XDAP:
o handles - unique identifiers assigned the IP address registry.
These handles are defined to have their type as the first part of
the handle. A query with a type "host" will yield a <hostInfo>
result. A query with a type "net" will yield a <networkInfo>
result. A query with a type "as" will yield a
<autonomousSystemInfo> result. The other types, "org", "person",
and "role" will yield a <contactInfo> result.
o host names - the fully qualified host names of nameservers.
Queries with these names will yield a <hostInfo> result. A host
may be multi-homed and therefore known by many host names.
o IP addresses - the address, either IP v4 or IP v6, of a
Newton Expires August 23, 2001 [Page 7]
Internet-Draft XDAP IP Directory Schema February 2001
nameserver or a network. Because both name servers and networks
are known by IP addresses, an entity lookup using an address will
result in either <hostInfo> or <networkInfo> results. In rare
cases where this may present a problem, a <hostOrNetwork> result
may be returned. The children of this element are entity
references, one to a name server and the other to a network.
o autonomous system numbers - yields a result of
<autonomousSystemInfo>.
Newton Expires August 23, 2001 [Page 8]
Internet-Draft XDAP IP Directory Schema February 2001
4. Formal XML Syntax
This IP address directory is specified in the XML Schema notation.
The formal syntax presented here is a complete schema representation
suitable for automated validation of an XML instance when combined
with the formal schema syntax of XDAP. Due to document formatting
restrictions, readers should note that the regular expressions
expressed in this schema DO NOT contain whitespace within the quotes
containing the regular expression.
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2000/10/XMLSchema"
xmlns:ipdir="urn:iana:xmlns:ipdir1"
xmlns:xdap="urn:iana:xmlns:xdap1"
targetNamespace="urn:iana:xmlns:ipdir1"
elementFormDefault="qualified" >
<annotation>
<documentation>
IP address directory schema
derived from XDAP schema
</documentation>
</annotation>
<!-- -->
<!-- Query types -->
<!-- -->
<complexType name="lookupContactType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="handle"
type="ipdir:handleType" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="lookupContact"
type="ipdir:lookupContactType"
substitutionGroup="xdap:query" />
<complexType name="findContactsType">
<complexContent>
<extension base="xdap:queryType">
<sequence>
<element name="beginsWith"
Newton Expires August 23, 2001 [Page 9]
Internet-Draft XDAP IP Directory Schema February 2001
type="CDATA" minLength="3"
minOccurs="1" maxOccurs="1" />
<element name="endsWith"
type="CDATA" minLength="2"
minOccurs="0" maxOccurs="1" />
<element name="type"
type="CDATA"
minOccurs="0" maxOccurs="1" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="findContacts"
type="ipdir:findContactsType"
substitutionGroup="xdap:query" />
<complexType name="lookupHostType">
<complexContent>
<extension base="xdap:queryType">
<choice>
<element name="handle"
type="ipdir:handleType" />
<element name="hostName"
type="ipdir:domainNameType" />
<element name="ipV4Address"
type="ipdir:dotQuadIPv4Type" />
<element name="ipV6Address"
type="ipdir:textIPv6AddressType" />
</choice>
</extension>
</complexContent>
</complexType>
<element name="lookupHost"
type="ipdir:lookupHostType"
substitutionGroup="xdap:query" />
<complexType name="lookupNetworkType">
<complexContent>
<extension base="xdap:queryType">
<choice>
<element name="ipV4Address"
type="ipdir:dotQuadIPv4Type" />
<element name="ipV6Address"
type="ipdir:textIPv6AddressType" />
</choice>
</extension>
</complexContent>
Newton Expires August 23, 2001 [Page 10]
Internet-Draft XDAP IP Directory Schema February 2001
</complexType>
<element name="lookupNetwork"
type="ipdir:lookupNetworkType"
substitutionGroup="xdap:query" />
<complexType name="lookupAutonomousSystemType">
<complexContent>
<extension base="xdap:queryType">
<choice>
<element name="number"
type="positiveInteger" />
<element name="handle"
type="ipdir:handleType" />
</choice>
</extension>
</complexContent>
</complexType>
<element name="lookupAutonomousSystem"
type="ipdir:lookupAutonomousSystemType"
substitutionGroup="xdap:query" />
<!-- -->
<!-- Result types -->
<!-- -->
<complexType name="hostInfoType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="hostName"
type="ipdir:domainNameType" />
<choice
minOccurs="1" maxOccurs="unbounded" >
<element name="ipV4">
<complexType>
<sequence>
<element name="ipV4Address"
type="ipdir:dotQuadIPv4Type" />
<element name="networkReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
</sequence>
</complexType>
</element>
<element name="ipV6">
<complexType>
<sequence>
Newton Expires August 23, 2001 [Page 11]
Internet-Draft XDAP IP Directory Schema February 2001
<element name="ipV6Address"
type="ipdir:textIPv6AddressType" />
<element name="networkReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
</sequence>
</complexType>
</element>
</choice>
<element name="contactReference"
type="uriReference" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="hostInfo"
type="ipdir:hostInfoType"
substitutionGroup="xdap:result" />
<complexType name="networkInfoType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="holderReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
<element name="contactReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
<element name="handle"
type="ipdir:handleType" />
<choice>
<element name="ipV4">
<complexType>
<sequence>
<element name="startIPv4"
type="ipdir:dotQuadIPv4Type" />
<element name="endIPv4"
type="ipdir:dotQuadIPv4Type" />
</sequence>
</complexType>
</element>
<element name="ipV6">
<complexType>
<sequence>
<element name="startIPv6"
type="ipdir:textIPv6AddressType" />
<element name="endIPv6"
Newton Expires August 23, 2001 [Page 12]
Internet-Draft XDAP IP Directory Schema February 2001
type="ipdir:textIPv6AddressType" />
</sequence>
</complexType>
</element>
</choice>
</sequence>
</extension>
</complexContent>
</complexType>
<element name="networkInfo"
type="ipdir:networkInfoType"
substitutionGroup="xdap:result" />
<complexType name="hostOrNetworkType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="nameServerReference"
type="uriReference" />
<element name="networkReference"
type="uriReference" />
</sequence>
</extension>
</complexContent>
</complexType>
<element name="hostOrNetwork"
type="ipdir:hostOrNetworkType"
substitutionGroup="xdap:result" />
<complexType name="autonomousSystemInfoType">
<complexContent>
<extension base="xdap:resultType">
<sequence>
<element name="holderReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
<element name="contactReference"
type="uriReference"
minOccurs="0" maxOccurs="1" />
<element name="handle"
type="ipdir:handleType" />
<element name="s