Request for Comments: 3981 VeriSign, Inc.
Category: Standards Track M. Sanz
DENIC eG
January 2005
IRIS: The Internet Registry Information Service (IRIS) Core Protocol
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2005).
Abstract
This document describes an application layer client-server protocol
for a framework to represent the query and result operations of the
information services of Internet registries. Specified in the
Extensible Markup Language (XML), the protocol defines generic query
and result operations and a mechanism for extending these operations
for specific registry service needs.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Use of XML . . . . . . . . . . . . . . . . . . . . . . . 2
1.2. General Concepts . . . . . . . . . . . . . . . . . . . . 3
1.3. Framework Layers . . . . . . . . . . . . . . . . . . . . 4
1.4. Definitions . . . . . . . . . . . . . . . . . . . . . . 4
1.5. Further Reading . . . . . . . . . . . . . . . . . . . . 5
2. Document Terminology . . . . . . . . . . . . . . . . . . . . . 5
3. Protocol Identification . . . . . . . . . . . . . . . . . . . 5
4. Exchange Description . . . . . . . . . . . . . . . . . . . . . 6
4.1. Request Format . . . . . . . . . . . . . . . . . . . . . 6
4.2. Response Format . . . . . . . . . . . . . . . . . . . . 6
4.3. Extension Framework . . . . . . . . . . . . . . . . . . 9
4.3.1. Derived Elements . . . . . . . . . . . . . . . . 9
4.3.2. Registry Type Identifier Requirements . . . . . 10
4.3.3. Entity Classes . . . . . . . . . . . . . . . . . 10
4.3.4. Names of Entities . . . . . . . . . . . . . . . 11
4.3.5. References to Entities . . . . . . . . . . . . . 11
4.3.6. Temporary Entities . . . . . . . . . . . . . . . 12
4.3.7. <result> Derived Elements . . . . . . . . . . . 13
4.3.8. <control> and <reaction> Elements . . . . . . . 16
4.4. Relay Bags . . . . . . . . . . . . . . . . . . . . . . . 18
5. Database Serialization . . . . . . . . . . . . . . . . . . . . 19
6. Formal XML Syntax . . . . . . . . . . . . . . . . . . . . . . 22
7. The IRIS URI . . . . . . . . . . . . . . . . . . . . . . . . . 37
7.1. URI Definition . . . . . . . . . . . . . . . . . . . . . 37
7.2. Transport Specific Schemes . . . . . . . . . . . . . . . 38
7.3. URI Resolution . . . . . . . . . . . . . . . . . . . . . 38
7.3.1. Registry Dependent Resolution . . . . . . . . . 38
7.3.2. Direct Resolution . . . . . . . . . . . . . . . 39
7.3.3. Transport and Service Location . . . . . . . . . 39
7.4. IRIS URI Examples . . . . . . . . . . . . . . . . . . . 40
8. Checklists . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8.1. Registry Definition Checklist . . . . . . . . . . . . . 41
8.2. Transport Mapping Checklist . . . . . . . . . . . . . . 42
9. Internationalization Considerations . . . . . . . . . . . . . 42
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43
11. Security Considerations . . . . . . . . . . . . . . . . . . . 43
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 43
12.1. Normative References . . . . . . . . . . . . . . . . . . 43
12.2. Informative References . . . . . . . . . . . . . . . . . 45
A. S-NAPTR and IRIS Uses . . . . . . . . . . . . . . . . . . . . 46
A.1. Examples of S-NAPTR with IRIS. . . . . . . . . . . . . . 46
A.2. Using S-NAPTR for Cohabitation . . . . . . . . . . . . . 47
B. IRIS Design Philosophy . . . . . . . . . . . . . . . . . . . . 48
B.1. The Basic Premise . . . . . . . . . . . . . . . . . . . 48
B.2. The Lure of a Universal Client . . . . . . . . . . . . . 49
B.3. Server Considerations . . . . . . . . . . . . . . . . . 49
B.4. Lookups, Searches, and Entity Classes . . . . . . . . . 50
B.5. Entities References, Search Continuations, and Scope . . 50
C. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 51
Authors’ Addresses . . . . . . . . . . . . . . . . . . . . . . . . 51
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 52
1. Introduction
The specification outlined in this document is based on the
functional requirements described in CRISP [17].
1.1. Use of XML
This document describes the specification for the Internet Registry
Information Service (IRIS), an XML text protocol intended to describe
the query types and result types of various registry information
services. IRIS is specified by using the Extensible Markup Language
(XML) 1.0 as described in [2], XML Schema notation as described in
[4] and [5], and XML Namespaces as described in [3].
1.2. General Concepts
Each kind of Internet registry is identified by a registry type. The
identifier for a registry type is a Uniform Resource Name (URN) used
within the XML instances to identify the XML schema that formally
describes the set of queries, results, and entity classes allowed
within that type of registry.
The structure of these URNs makes no assumptions or restrictions on
the types of registries they identify. Therefore, IRIS may support
multiple registry types of a disparate or similar nature; it is only
a matter of definition. For instance, a single registry type may be
defined for domain name registries, and multiple registry types for
the various IP address registries.
A registry information server may handle queries and serve results
for multiple registry types. Each registry type that a particular
registry operator serves is a registry service instance.
IRIS and the XML schema formally describing IRIS do not specify any
registry, registry identifier, or knowledge of a particular service
instance or set of instances. IRIS is a specification for a
framework with which these registries can be defined, used and, in
some cases, interoperate. The framework merely specifies the
elements for registry identification and the elements that must be
used to derive queries and results.
This framework allows a registry type to define its own structure for
naming, entities, queries, etc., through the use of XML namespaces
and XML schemas (hence, a registry type MUST be identified by the
same URI that identifies its XML namespace). To be compliant, a
registry type’s specification must extend from this framework.
The framework defines certain structures that can be common to all
registry types, such as references to entities, search continuations,
and entity classes. A registry type may declare its own definitions
for all of these, or it may mix its derived definitions with the base
definitions.
IRIS 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 distributed
searches. Both referrals may span differing registry types and
instances. No assumptions or specifications are made about the
roots, bases, or meshes of entities.
1.3. Framework Layers
The IRIS framework can be thought of as having three layers.
-----------------------------
Registry-Specific |domain | address | etc... |
-----------------------------
Common-Registry | IRIS |
-----------------------------
Application-Transport | beep | iris-lwz | etc... |
-----------------------------
In this figure, "beep" refers to the Blocks Extensible Exchange
Protocol (BEEP) (see [20]), and "iris-lwz" refers to a theoretical
UDP binding that uses compression.
The differing layers have the following responsibilities:
Registry-Specific :: defines queries, results, and entity classes
of a specific type of registry. Each specific type of registry is
identified by a URN.
Common-Registry :: defines base operations and semantics common to
all registry types such as search sets, result sets, and
referrals. It also defines the syntaxes for talking about
specific registry types.
Application-Transport :: defines the mechanisms for
authentication, message passing, connection and session
management, etc. It also defines the URI syntax specific to the
application-transport mechanism.
1.4. Definitions
For clarity, the following definitions are supplied:
o registry type -- A registry serving a specific function, such as a
domain registry or an address registry. Each type of registry is
assigned a URN.
o registry schema -- The definition for a registry type specifying
the queries, results, and entity classes.
o authority -- A reference to the server or set of servers
containing information.
o resolution method -- The technique used to locate an authority.
o entity class -- A group of entities with a common type or common
set of characteristics.
o entity name -- The identifier used to refer to a single entity
within an entity class.
o entity reference -- A pointer to an entity composed of an
authority, an optional resolution method, a registry type, an
entity class, and an entity name. One type of entity reference is
the IRIS URI (defined in Section 7).
The terms "derivative", "derive", and "derivation" are used with the
same meaning for deriving one type of element from another as
specified in XML_SS [5].
1.5. Further Reading
Appendix B contains text answering the question, "Why IRIS?".
This document describes the structure at the core of IRIS. The
following documents describe the other aspects of IRIS relevant to
CRISP [17]: iris-beep [1] and iris-dreg [18].
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 BCP 14, RFC 2119 [8].
3. Protocol Identification
The root element of all request XML instances MUST be <request>. The
root element of all response XML instances MUST be <response>. These
elements identify the start of the IRIS elements, the XML namespace
used as the identifier for IRIS, and, optionally, the location of the
schema. These elements and the associated closing tag MUST be
applied to all requests and responses sent by both clients and
servers.
The use of the schema location attribute ’xsi:schemaLocation’ is
OPTIONAL with respect to this specification, and IRIS implementations
MAY resolve it to retrieve the schema or MAY use a locally cached
version of the schema.
Versioning of the IRIS protocol is the responsibility of the
application-transport layer but MUST be associated with the XML
namespace [3] URI representing IRIS. A change in this URI indicates
a change of the underlying schema and, therefore, a new version of
the protocol (and vice versa).
4. Exchange Description
This section describes the request and response exchanges of the
protocol. The descriptions contained within this section refer to
XML elements and attributes and their relation to the exchange of
data within the protocol. These descriptions also contain
specifications outside the scope of the formal XML syntax.
Therefore, this section will use terms defined by RFC 2119 [8] to
describe the specification outside the scope of the formal XML
syntax. While reading this section, please reference Section 6 for
details on the formal XML syntax.
4.1. Request Format
A <request> element contains an optional <control> element and a set
of <searchSet> elements.
The <searchSet> elements enable a client to query a particular
registry type by using the URN identifying the registry type. This
can be found in one of its two children: <lookupEntity> and <query>.
The <lookupEntity> element describes the lookup of an entity in a
specific registry. This element has three attributes:
’registryType’, ’entityClass’, and ’entityName’. The ’registryType’
attribute contains the registry identifier for the registry type in
which the lookup operation will take place. The ’entityClass’
attribute contains the token identifying the index for which the
lookup operation will take place, and the ’entityName’ attribute
contains the name of the entity to look up.
The <query> element is abstract and may not legally appear in an XML
instance. It provides the base type that registry schemas will use
to define derived query types. This derivation mechanism is
described in Section 4.3.
Each <searchSet> may also contain a <bag> element. When this element
appears as a child of <searchSet>, it MUST NOT contain the ’id’
attribute. For a description of the <bag> element, see Section 4.4.
The <control> element may contain one child element of any XML
namespace. This child element allows a client to signal a server for
special states or processing. An example of one such <control> child
element may be found in Section 4.3.8.
4.2. Response Format
The <response> element contains an optional <reaction> element, a set
of <resultSet> elements, and an optional <bags> element.
The <resultSet> elements are responses to a <searchSet> request. The
contents of this element contain an <answer> element, an optional
<additional> element, and error elements, if applicable.
The children of the <answer> element are 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 registry
schemas to define derived result types. This derivation mechanism
is described in Section 4.3.
o <entity> is an element specifying an entity reference. See
Section 4.3.5.
o The <searchContinuation> element specifies a query referral. Its
one child is any element derived from <query> (see Section 4.3.1).
To direct the query to a referent server, <searchContinuation> has
a mandatory ’authority’ attribute and an optional ’resolution’
attribute. The <searchContinuation> element may also contain a
’bagRef’ attribute. For a description of the ’bagRef’ attribute,
see Section 4.4.
When following entity references and search continuations, clients
SHOULD only follow an <entity> or <searchContinuation> response once.
Failure to do so may result in the client process getting stuck in a
never-ending query loop, commonly known as a referral loop.
The <additional> element only contains <result> elements, as
described above. This element allows a server to indicate to a
client results that were not specifically queried but that are
related to the queried results, thus enabling the client to display
this distinction to a user properly. The <additional> element use is
optional.
The following elements, which represent error conditions, may be
returned:
o <insufficientResources> -- The corresponding query requires
resources unobtainable by the server.
o <invalidName> -- A name given in a query is not syntactically
correct.
o <invalidSearch> -- Parameters of the corresponding query are not
semantically meaningful.
o <queryNotSupported> -- The corresponding query is not supported by
this server.
o <limitExceeded> -- The corresponding query requires more resources
than allowed.
o <nameNotFound> -- The name given in a query does not match a known
entity.
o <permissionDenied> -- The authentication given does not allow
access to a specific result entry.
o <bagUnrecognized> -- The contents of a bag were unrecognized. See
Section 4.4.
o <bagUnacceptable> -- The contents of a bag were not and never will
be acceptable. See Section 4.4.
o <bagRefused> -- The contents of a bag were not acceptable at this
time. See Section 4.4.
o A derivative of <genericCode>, as described in Section 4.3.
The <resultSet> section is divided into the <answer> and <additional>
sections to allow easier processing and navigation of the results by
a client. Servers MUST return the direct answers to queries in the
<answer> element and MAY return results in the <additional> element
for which a reference has been made in the <answer> element. Results
in the <additional> element MUST have been referenced in the
<answer>, either as direct children of the <answer> element or as
deeper descendants of the <answer> element.
This serves two purposes. First, it may eliminate a requery by the
client for references contained in the <answer> element. Second, it
distinguishes between results that are a direct result of a query and
those that would have been returned had the client followed the
appropriate referrals, thus hinting how clients could process or
display the returned results. For instance, clients constructing
complex displays with tree navigation widgets will know that results
in the <answer> element should all be directly beneath the root node
of the tree, while results in the <additional> element are leaf nodes
of those produced from the <answer> element.
A <reaction> element (child of <response>) is a response to a
<control> element, and provides a means for a server to advise a
client of the effect of a <control> element.
The <bags> element (child of <response>) is optional. It contains
<bag> elements, and the contents of each <bag> element constitute one
element in any XML namespace. Each <bag> element has an ’id’
attribute, which is referenced by the ’bagRef’ attribute of entity
references (<entity>) and search continuations
(<searchContinuation>). See Section 4.4.
4.3. Extension Framework
Because the IRIS schema defines only one query type, and two stand-
alone result types, and does not define a registry structure, it is
of limited use by itself. Extension of IRIS is accomplished through
the use of a base IRIS schema, as defined in XML_SD [4] and XML_SS
[5], and through extension of it by schemas constructed on top of
IRIS.
4.3.1. Derived Elements
The XML Schema definition of IRIS requires schemas of registry types
to derive element types from base types in the IRIS definition. The
registry schemas MUST derive elements to define typed queries and
results.
While the IRIS schema definition does not prohibit the derivation of
any elements, registry 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 its
derivatives appear in XML instances. Registry schemas derive from
this element to define the queries allowed.
o <result> -- As defined, this element contains no content and has
five valid attributes: ’authority’, ’resolution’ (optional),
’registryType’, ’entityClass’, ’entityName’, and
’temporaryReference’ (optional, see Section 4.3.6). It is
abstract and therefore only its derivatives appear in XML
instances. Registry schemas derive from this element to define
results that may be returned from a query.
o <genericCode> -- As defined, this element is an instance of
<codeType>. It contains the optional elements <explanation> and
<language>, which further describe the nature of the error.
o <entity> -- Identifies a reference to an entity. Registry schemas
SHOULD use elements derived from <entity> but MAY use <entity>
directly. The advantage of deriving from <entity> vs. direct use
is the chance to define the name of the element and to use that
name descriptively -- for instance, as the role the entity plays
with respect to another entity. See Section 4.3.5.
o <seeAlso> -- Indicates a reference to an entity that has indirect
association with a parent element representing an entity. This
element is derived from the <entity> element (Section 4.3.5).
Registry schemas MAY derive from this element or MAY use it
directly.
4.3.2. Registry Type Identifier Requirements
The identifier for a registry type and the XML namespace identifier
used by the XML Schema describing the registry MUST be the same.
These identifiers MUST be restricted to a URN [7] registered in the
’ns’ class of the IANA registry governed by XML_URN [9]. These
identifiers are case insensitive.
This is a restriction on XML_NS [3], which specifies that an XML
namespace identifier is any valid URI [6].
These identifiers MAY be abbreviated to the part following the class
component and its separator of the URN. For example, the full URN
"urn:ietf:params:xml:ns:dreg1" may be abbreviated to "dreg1".