RFC 3981
IRIS: The Internet Registry Information Service (IRIS) Core Protocol
Part 1 of 9 💖
IRIS: The Internet Registry Information Service (IRIS) Core Protocol 🎀
okay bestie, this is RFC 3981 🦋 and it's the core spec for IRIS. Here's the vibe check on the title block:
- Written by: A. Newton (VeriSign, Inc.) and M. Sanz (DENIC eG) 💅
- Category: Standards Track 🌈
- Date: January 2005 ⭐
- Network Working Group: the group that published it 🧚
- Obsoletes / Updates: the header doesn't list anything it obsoletes or updates 🙈
Status of This Memo 📜
This doc specifies an Internet standards track protocol for the Internet community, and it's literally asking everyone to discuss it and send suggestions for improvements 🫶. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌸.
Copyright Notice ©️
Copyright (C) The Internet Society (2005).
Abstract ✨
So the abstract says this is an application layer client-server protocol for a framework that represents the query and result operations of the information services of Internet registries 🔥. It's specified in the Extensible Markup Language (XML), and it defines generic query and result operations plus a mechanism for extending them 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 . . . . . . . . . . . . . . . . . . . . . 521. Introduction 🌈
The spec in this doc is based on the functional requirements described in CRISP [17]. So CRISP is the foundation here 🧱.
1.1. Use of XML 💜
This document describes the specification for the Internet Registry Information Service (IRIS), an XML text protocol meant to describe the query types and result types of various registry information services 💅. IRIS is specified using 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. Picture it like this:
-----------------------------
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, here are the definitions:
- 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.
- registry schema: The definition for a registry type specifying the queries, results, and entity classes.
- authority: A reference to the server or set of servers containing information.
- resolution method: The technique used to locate an authority.
- entity class: A group of entities with a common type or common set of characteristics.
- entity name: The identifier used to refer to a single entity within an entity class.
- 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]. These are the capitalised key words that carry the requirement levels, so watch for them 👑.
3. Protocol Identification ✨
okay bestie, the root element of every request XML instance MUST be <request> 💖, and the root element of every response XML instance MUST be <response> 🎀. these elements basically announce "hi, this is IRIS!!" 🧚 They mark the start of the IRIS elements, they carry the XML namespace used as IRIS's identifier, and optionally they point to 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, no exceptions 💅
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 it 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). It's giving "the URI is the version" energy 👑
4. Exchange Description 🌈
this section describes the request and response exchanges of the protocol 💌. The descriptions here refer to XML elements and attributes and how they relate to the exchange of data within the protocol. They also contain specifications outside the scope of the formal XML syntax. So this section uses terms defined by RFC 2119 [8] to describe those outside-the-syntax specifications 🤓. While you're reading, 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 let a client query a particular registry type by using the URN that identifies the registry type. You'll find this in one of its two children: <lookupEntity> and <query> 🔍.
The <lookupEntity> element describes looking up an entity in a specific registry. It has three attributes: registryType, entityClass, and entityName 🧸. The registryType attribute contains the registry identifier for the registry type where the lookup will happen. The entityClass attribute contains the token identifying the index the lookup will use, and the entityName attribute contains the name of the entity being looked up ✨.
The <query> element is abstract and may not legally appear in an XML instance. It's the base type that registry schemas 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 from any XML namespace. This child element lets a client 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. Their contents include an <answer> element, an optional <additional> element, and error elements, if applicable 📦.
The children of the <answer> element are of the following types:
<result>is an abstract element and may not be legally placed in an XML instance. It provides the base type that registry schemas use to define derived result types. This derivation mechanism is described in Section 4.3.<entity>is an element specifying an entity reference. See Section 4.3.5.- 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 mandatoryauthorityattribute and an optionalresolutionattribute. The<searchContinuation>element may also contain abagRefattribute. For a description of thebagRefattribute, 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 🙈. Bestie, don't be that client 😭.
The <additional> element only contains <result> elements, as described above. This element lets a server tell a client about results that weren't specifically queried but that are related to the queried results 🌈. That way the client can show this distinction to a user properly. Use of the <additional> element is optional ✨.
The following elements, which represent error conditions, may be returned 🚨:
<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.<queryNotSupported>-- The corresponding query is not supported by this server.<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.<bagUnrecognized>-- The contents of a bag were unrecognized. See Section 4.4.<bagUnacceptable>-- The contents of a bag were not and never will be acceptable. See Section 4.4.<bagRefused>-- The contents of a bag were not acceptable at this time. See Section 4.4.- A derivative of
<genericCode>, as described in Section 4.3.
The <resultSet> section is split into the <answer> and <additional> sections so a client can process and navigate results more easily 🗂️. Servers MUST return the direct answers to queries in the <answer> element. They 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 it 💅.
This serves two purposes. First, it may eliminate a requery by the client for references contained in the <answer> element 🙌. Second, it tells apart results that come straight from a query from those that would have been returned had the client followed the appropriate referrals. That hints at how clients could process or display the results 👀. For instance, clients building complex displays with tree navigation widgets will know that results in the <answer> element should all sit 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. It gives a server a way to tell a client what effect a <control> element had 🎀.
The <bags> element (child of <response>) is optional 🧺. It contains <bag> elements, and the contents of each <bag> element make up one element from 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 doesn't define a registry structure, it's of limited use by itself 🥺. Extending IRIS happens through a base IRIS schema, as defined in XML_SD [4] and XML_SS [5], and through schemas built on top of IRIS that extend it 💖.
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 doesn't prohibit deriving any elements, registry schemas SHOULD restrict the derivations to the following types:
<query>-- As defined, this element contains no content and has no valid attributes. It is abstract, so only its derivatives appear in XML instances. Registry schemas derive from this element to define the queries allowed.<result>-- As defined, this element contains no content and has five valid attributes:authority,resolution(optional),registryType,entityClass,entityName, andtemporaryReference(optional, see Section 4.3.6). It is abstract, so only its derivatives appear in XML instances. Registry schemas derive from this element to define results that may be returned from a query 🎁.<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 🚨.<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>instead of using it directly is the chance to define the element's name and to use that name descriptively, for instance as the role the entity plays with respect to another entity. See Section 4.3.5 🏷️.<seeAlso>-- Indicates a reference to an entity that has an 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 ✂️.
In use with IRIS, this abbreviation MUST NOT be used inside of XML instances in which the XML Schema [4] specifies the use of a URI for schema identification, or where XML_NS [3] specifies the use of a URI for XML namespace identification. So no shortcuts there, bestie 🙅♀️💜
4.3.3. Entity Classes ✨
okay so IRIS gives us entity classes 🎀 bestie, they're how we stop entity names from crashing into each other inside a registry type 💅 Specifying one in a query also lets the server zoom straight into a single index instead of searching everything. so efficient 🦋
Here's the vibe. The entity name 192.0.2.0 could mean totally different things depending on the class. In the name-server class, it might be the name server host that's also multi-homed by address 192.0.2.255 and known in DNS as ns.example.com. In the network class, that same 192.0.2.0 might be the network 192.0.2/30. Same name, two iconic identities 👑
IRIS defines two default entity classes, local and iris, and these MUST NOT be redefined 🚫 They also MUST be valid in all registry types, so they're always there for you 🫶
The local class is reserved for entities a server operator defines locally, and it doesn't mean any particular type of entity 🌸 A lookup in this class MAY result in an entity reference or a search continuation. For example, iris:dreg1//example.com/local/myhosts may result in a search continuation yielding the nameservers for example.com.
The iris class is reserved for entities specific to a particular service instance 💖 It MUST contain the following entity names (see Section 4.3.4):
id, which yields a result of<serviceIdentification>(see Section 4.3.7.1).limits, which yields a result of<limits>(see Section 4.3.7.2). This entity class MAY contain other locally defined entities as well.
The names of entity classes in a registry schema are of type token, as defined by XML_SD [4] 🧚 Their case sensitivity MUST be defined by the definition of the registry type. In general, they SHOULD be case insensitive, so don't stress about capitals 🍓
4.3.4. Names of Entities 🌈
The names of entities in a registry schema are of type token, as defined by XML_SD [4] 💜
Names of entities SHOULD be unique within an instance of any particular entity class within a registry. Two entities SHOULD NOT have the same name, but a single entity MAY be known by multiple names 🦋 When one name could point to two entities, the registry schema SHOULD make allowances by defining result types that contain entity references to both of them. For example, example.com can refer to both the domain example.com and the host example.com 🌸 Still, this kind of conflict SHOULD generally be avoided by using entity classes properly.
The case sensitivity of entity names depends on the entity class they live in 🎀 The definition of a registry type MUST specify the case sensitivity for entity names. A registry type MAY define the entity names of differing entity classes as having different case sensitivity. very particular, very iconic 💅
4.3.5. References to Entities 🔥
The <entity> element lets you reference entities in result sets, either as a direct child of <resultSet> or inside a more complex structure built from <result> 🫶 The <entity> element is defined by 'entityType'. Registry schemas SHOULD define elements derived from <entity> when they reference entities, but they MAY use <entity> directly. Deriving a new element lets a schema use the element's name to signal the relationship between the referenced entity and the referrer, which is honestly genius 🧠 A derivative of <entity> MUST NOT be used as a substitute where the <entity> element is declared (such as in the <answer> section of the <resultSet>).
The <entity> element (and elements of type 'entityType') can have child elements of <displayName>, each with an optional 'language' attribute 🌷 These exist so servers can give clients a more human-friendly description of the entity reference. Super useful for users navigating referral structures 🧭
The <entity> element (and its derivations) has the following attributes:
- 'authority', 'resolution' (optional), 'registryType', 'entityClass', and 'entityName' -- these tell you where the entity may be found 📍
- 'temporaryReference' -- this attribute is optional. See Section 4.3.6.
- 'referentType' -- this attribute holds the expected type of the referenced entity and may contain the word "ANY" or a qualified XML name. Unlike the other
<entity>attributes, this one is qualified and declared in the IRIS XML namespace, so it's also qualified with the prefix associated with that namespace (e.g.,iris:referentType) 🎀 This lets clients recognize entity references made with an element derived from<entity>. - 'bagRef' -- this attribute is optional. If present, it must contain an XML identifier pointing to a
<bag>element in the<bags>section of the result set. For a description of 'bagRef', see Section 4.4 🦋
4.3.6. Temporary Entities 🌸
okay this one is a little plot twist 🙈 Sometimes an entity reference needs to be temporary. For example, a particular type of result may only have one unique key. If that key carries semantic meaning that shouldn't be exposed to all users, a synthetic key has to be swapped in 🔐
Also, the data in the data store might not be normalized the same way the registry schema expresses it. In the schema, objects of type A may reference objects of type B. But in the data store, objects of type A may contain objects of type B. Again, a synthetic key has to be temporarily produced ✨
To support these cases, results and entity references can be declared temporary using the temporaryReference attribute 💜 This attribute is of type boolean [4] and has a default value of "false". It's optional for <result> derivatives and for elements of type 'entityType'.
When this attribute is used, the entity reference data (e.g., 'entityClass', 'entityName') is only valid within the response it appears in, and it may not be consistent with later responses. Heads up, bestie: a server MUST include the referent of any temporary entity reference in the <additional> section of the same <resultSet>.
4.3.7. <result> Derived Elements 👑
The base IRIS framework has three elements derived directly from the <result> element, and any registry type can use them 💅
4.3.7.1. <serviceIdentification> 🧚
Here's an example of a <serviceIdentification> result:
<serviceIdentification
authority="example.com" registryType="dreg1"
entityClass="iris"
entityName="id" >
<authorities>
<authority> example.com </authority>
<authority> example.net </authority>
<authority> example.org </authority>
</authorities>
<operatorName>
Internet Assigned Numbers Authority
</operatorName>
<eMail>
iana@iana.org
</eMail>
</serviceIdentification>The <serviceIdentification> element lets IRIS clients reference IRIS service instances 🦋 It contains the following elements:
<authorities>-- contains one or more<authority>elements. Each<authority>holds a URI authority component the server has results for. A server MAY only return a partial list of its authority areas, depending on operator policy, but it MUST return the authority the client requested 🫶<operatorName>-- the name of the server's operator 🏢<eMail>-- optional elements with email addresses of the service instance's operator 📧<phone>-- optional elements with phone numbers of the service instance's operator 📞<seeAlso>-- see Section 4.3.1 for its definition.
4.3.7.2. <limits> 🔥
Here's an example of a <limits> result:
<limits
authority="example.com" registryType="dreg1"
entityClass="iris" entityName="limits">
<totalQueries>
<perHour>2</perHour>
<perDay>15</perDay>
</totalQueries>
<totalResults>
<perHour>25</perHour>
<perDay>200</perDay>
</totalResults>
<totalSessions>
<perHour>2</perHour>
<perDay>15</perDay>
</totalSessions>
</limits>The <limits> element is the server's way of telling a client what limits it might run into if the service gets overused 🚦 The contents describe the service limitations at the client's current level of access. Here's what goes inside:
<totalQueries>-- the total number of queries the server will accept. The children give this number per unit of time:<perSecond>,<perMinute>,<perHour>, and<perDay>. Each child MUST only appear once as a child of<totalQueries>, but more than one child MAY be present. For example, a server could say it accepts 15 queries a minute but only 60 queries a day 🧮<totalResults>-- the total number of results the server will send to a client. Its children give this number per unit of time, same as<totalQueries>📦<totalSessions>-- the total number of sessions the server will accept from a client. Its children give this number per unit of time, same as<totalQueries>. A session is defined by the application transport layer 🛰️<otherRestrictions>-- describes other restrictions that may only be expressible outside the structured syntax of the other<limits>children. It may have optional<description>child elements, each with a mandatory 'language' attribute 📝<seeAlso>-- these elements reference other entities, such as a<simpleEntity>(Section 4.3.7.3) describing a published policy. See<seeAlso>(Section 4.3.1).
All of these child elements are optional 🥰 A server may express that it has no limits by using a <limits> element with no content (e.g., <limits authority=... />).
4.3.7.3. <simpleEntity> 🌷
Here's an example of a <simpleEntity> result:
<simpleEntity
authority="example.com" registryType="dreg1"
entityClass="local"
entityName="notice" >
<property name="legal" language="en">
Example.com is reserved according to RFC 2606.
</property>
</simpleEntity>The <simpleEntity> element exists so service operators can make simple additions to other entities without deriving whole new registry types 🧁 Its definition lets operators reference it from other entities (using, for instance, a <seeAlso> element). It's meant to represent name and value pairs of strings, where each pair can have a specific language qualifier and an optional URI pointing to more information 🌈
Clients can easily display this info in a two-column table 📊 Applications using binary data or richer data structures are out of scope for this element. When those scenarios come up, a client will likely need specific knowledge to handle the data, which calls the need for a new registry type into question 🤔
4.3.8. <control> and <reaction> Elements ✨
okay so the <control> (Section 4.1) and <reaction> (Section 4.2) elements are how the client asks the server to switch into special states while it processes queries 💅 The whole point is extensibility, so some jurisdictions can adopt their own query-processing policies without needing to re-version IRIS or any registry type 🌈
This document defines one control, <onlyCheckPermissions>, and its requisite reaction, <standardReaction>, for compliance with CRISP [17] 🦋
When a client sends an <onlyCheckPermissions> control, it's only asking the server to check whether adequate permissions are available to execute the queries in the associated request 🔐 A server MUST respond to this control with a <standardReaction> element 💖
The <standardReaction> element gives the server a standard way to respond to controls (it may be used by other controls, but that's left to their definition) ✨ It has four children:
<controlAccepted>-- the processing or state needed by the control has been accepted. ✅<controlDenied>-- the processing or state needed by the control has been denied (a transient failure). ⏳<controlDisabled>-- the processing or state needed by the control cannot be activated (a permanent failure). 🚫<controlUnrecognized>-- the control is not recognized (a permanent failure). 🙈
If <onlyCheckPermissions> is rejected, then the server MUST return all appropriate result sets (i.e., for every search set in the request), but all result sets MUST be empty of results and MUST contain no errors (a reaction is not part of a result set and is therefore not a result set error) 🙈 This control applies to all search sets or none of them, so a server MUST issue a rejection if <onlyCheckPermissions> cannot be accepted for all search sets in a request 💀
An example of an IRIS XML exchange using these elements follows:
C: <?xml version="1.0"?>
C: <request xmlns="urn:ietf:params:xml:ns:iris1"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
C:
C: <control>
C: <onlyCheckPermissions />
C: </control>
C:
C: <searchSet>
C:
C: <lookupEntity
C: registryType="dreg1"
C: entityClass="local"
C: entityName="AUP" />
C:
C: </searchSet>
C:
C: </request>
S: <?xml version="1.0"?>
S: <response xmlns="urn:ietf:params:xml:ns:iris1"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
S:
S: <reaction>
S: <standardReaction>
S: <controlAccepted />
S: </standardReaction>
S: </reaction>
S:
S: <resultSet>
S: <answer>
S:
S: <simpleEntity
S: authority="example.com" registryType="dreg1"
S: entityClass="local" entityName="AUP" >
S: <property name="legal" language="en">
S: It is illegal to use information from this service
S: for the purposes of sending unsolicited bulk email.
S: </property>
S: </simpleEntity>
S:
S: </answer>
S: </resultSet>
S:
S: </response>4.4. Relay Bags 🎀
IRIS uses bags to let a server relay information to a referent server via the client 🧚 The queried server generates these bags, hands them to the client as opaque data, and then the client passes them to the referent server for processing. IRIS doesn't define what's inside the bags, and the client MUST NOT make any assumptions about the contents of a bag when relaying it from one server to another 🙅
When a server returns a result set to a client, the <response> element may contain a <bags> child element. This child element contains one or more <bag> elements. Each of these MUST contain an 'id' attribute containing the XML data type ID. Entity references and search continuations that have to specify a bag to be used when they are followed MUST have a 'bagRef' attribute containing the XML data type IDREF. See Section 4.2. This allows the response to specify a bag only once but allows each entity reference or search continuation (in all result sets) to have a distinct bag, as needed 🍓
When following an entity reference or search continuation that specifies the use of a bag, the client MUST include the referenced bag in the search set as a child of the <searchSet> element. See Section 4.1.
See Section 4.2 for the list of errors a server may return to a client when a bag is received. A server MUST NOT ignore a bag when it is received. In case a bag cannot be recognized or accepted, one of the errors from Section 4.2 MUST be returned 🚨
An example of an IRIS XML exchange using these elements follows:
C: <?xml version="1.0"?>
C: <request xmlns="urn:ietf:params:xml:ns:iris1"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
C:
C: <searchSet>
C:
C: <bag>
C: <simpleBag xmlns="http://example.com/">
C: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
C: </simpleBag>
C: </bag>
C:
C: <lookupEntity
C: registryType="dreg1"
C: entityClass="local"
C: entityName="AUP" />
C:
C: </searchSet>
C:
C: </request>
S: <?xml version="1.0"?>
S: <response xmlns="urn:ietf:params:xml:ns:iris1"
S: xmlns:iris="urn:ietf:params:xml:ns:iris1"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
S:
S: <resultSet>
S: <answer>
S:
S: <entity authority="example.com" bagRef="x1"
S: registryType="dreg1"
S: entityClass="local" entityName="AUP"
S: iris:referentType="ANY" >
S: <displayName language="en">
S: Acceptable Usage Policy
S: </displayName>
S: </entity>
S:
S: </answer>
S: </resultSet>
S:
S: <bags>
S:
S: <bag id="x1">
S: <simpleBag xmlns="http://example.com/">
S: AAAAB3NzaC1yc2EAAAABIwAAAIEA0ddD+W3Agl0Lel98G1r77fZ
S: </simpleBag>
S: </bag>
S:
S: </bags>
S: </response>5. Database Serialization 🌸
This section describes a method for serializing IRIS registry entities 📚 The descriptions here refer to XML elements and attributes and how they relate to this serialization process. They also contain specifications outside the scope of the formal XML syntax. This section will use terms defined by RFC 2119 [8] to describe these. While reading this section, please reference Section 6 for needed details on the formal XML syntax.
A database of IRIS entities can be serialized to file storage with XML [2] by using the IRIS defined <serialization> element. This element contains <result> element derivatives and <serializedReferral> elements.
Derivatives of the <result> element are entities. Servers loading these entities MUST place the entity in the entity classes specified by the elements 'registryType', 'entityClass', and 'entityName' attributes and in any entity classes the entities may apply according to explicitly defined children of that element. For instance, if a registry type has two entity classes "foo" and "bar" and a <result> derivative has the attributes entityClass="foo" and entityName="one" and a child element <bar>two</bar>, the server is to enter that entity into the entity class "foo" as the name "one" and into the entity class "bar" as the name "two" 🧩
Servers loading entities as serialized derivatives of the <result> element MAY translate the authority attribute. Servers will likely have to do this if the authority for the entity has changed.
<serializedReferral> elements allow the serialization of explicit entity references and search continuations. This element has a child <source> element containing the 'authority', 'resolution' (optional), 'registryType', 'entityClass', and 'entityName' attributes. The attributes of this element are used to signify the entity that can be referenced to yield this referral.
As mentioned above, there may be times when a server needs to translate the authority attribute of a loaded entity. Implementations must also beware of this need for referrals. During deserialization, servers MUST change the authority attribute of a referral (either <entity> or elements derived from <entity> or <source> child of <serializedReferral>) to contain a valid authority of the server if the serialized attribute is empty. During serialization, servers and their related processes MUST leave the authority attribute empty for referrals in which the referent is an entity for which the server answers queries 🫶
The following is an example of serialized IRIS:
<iris:serialization
xmlns:iris="urn:ietf:params:xml:ns:iris1"
xmlns="urn:ietf:params:xml:ns:iris1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<serviceIdentification
authority="iana.org" registryType="dreg1"
entityClass="iris"
entityName="id" >
<authorities>
<authority> iana.org </authority>
</authorities>
<operatorName>
Internet Assigned Numbers Authority
</operatorName>
<eMail>
dbarton@iana.org
</eMail>
<seeAlso
iris:referentType="iris:simpleEntity"
authority="iana.org" registryType="dreg1"
entityClass="local"
entityName="notice">
<displayName language="en">
Legal Notice
</displayName>
</seeAlso>
</serviceIdentification>
<serializedReferral>
<source
authority="example.com" registryType="dreg1"
entityClass="iris"
entityName="id"/>
<entity
iris:referentType="iris:serviceIdentification"
authority="iana.org" registryType="dreg1"
entityClass="iris" entityName="id"/>
</serializedReferral>
<simpleEntity
authority="iana.org" registryType="dreg1"
entityClass="local"
entityName="notice" >
<property name="legal" language="en">
Please use the net wisely!
</property>
</simpleEntity>
</iris:serialization>6. Formal XML Syntax 💖
IRIS is specified in XML Schema notation. The formal syntax presented here is a complete schema representation of IRIS suitable for automated validation of IRIS XML instances 🎀
<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:iris="urn:ietf:params:xml:ns:iris1"
targetNamespace="urn:ietf:params:xml:ns:iris1"
elementFormDefault="qualified" >
<annotation>
<documentation>
Internet Registry Information Service (IRIS) Schema v1
</documentation>
</annotation>
<!-- ========================================= -->
<!-- -->
<!-- The Transactions -->
<!-- -->
<!-- ========================================= -->
<element name="request">
<complexType>
<sequence>
<element
name="control"
type="iris:controlType"
minOccurs="0"
maxOccurs="1" />
<element
name="searchSet"
type="iris:searchSetType"
minOccurs="1"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>okay the schema is about to get SO good 🎀 the response wrapper comes first, then the search and result sets 💅
<element name="response">
<complexType>
<sequence>
<element
name="reaction"
type="iris:reactionType"
minOccurs="0"
maxOccurs="1" />
<element
name="resultSet"
type="iris:resultSetType"
minOccurs="1"
maxOccurs="unbounded" />
<element
name="bags"
type="iris:bagsType"
minOccurs="0"
maxOccurs="1" />
</sequence>
</complexType>
</element>
<!-- ========================================= -->
<!-- -->
<!-- Search Sets and Result Sets -->
<!-- -->
<!-- ========================================= -->
<complexType
name="searchSetType" >
<sequence>
<element
name="bag"
type="iris:bagType"
minOccurs="0"
maxOccurs="1" />
<choice>
<element
name="lookupEntity"
type="iris:lookupEntityType" />
<element
ref="iris:query" />
</choice>
</sequence>
</complexType>
<complexType
name="resultSetType" >
<sequence>
<element
name="answer"
minOccurs="1"
maxOccurs="1">
<complexType>
<sequence>
<element
ref="iris:result"
minOccurs="0"
maxOccurs="unbounded" />
<element
ref="iris:entity"
minOccurs="0"
maxOccurs="unbounded" />
<element
ref="iris:searchContinuation"
minOccurs="0"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
<element
name="additional"
minOccurs="0"
maxOccurs="1">
<complexType>
<sequence>
<element
ref="iris:result"
minOccurs="1"
maxOccurs="unbounded" />
</sequence>
</complexType>
</element>
<choice
minOccurs="0"
maxOccurs="1" >
<element
name="insufficientResources"
type="iris:codeType" />
<element
name="invalidName"
type="iris:codeType" />
<element
name="invalidSearch"
type="iris:codeType" />
<element
name="queryNotSupported"
type="iris:codeType" />
<element
name="limitExceeded"
type="iris:codeType" />
<element
name="nameNotFound"
type="iris:codeType" />
<element
name="permissionDenied"
type="iris:codeType" />
<element
name="bagUnrecognized"
type="iris:codeType" />
<element
name="bagUnacceptable"
type="iris:codeType" />
<element
name="bagRefused"
type="iris:codeType" />
<element
ref="iris:genericCode"/>
</choice>
</sequence>
</complexType>
<!-- ========================================= -->
<!-- -->
<!-- Controls and Reactions -->
<!-- -->
<!-- ========================================= -->
<complexType
name="controlType">
<sequence>
<any
namespace="##any"
processContents="skip"
minOccurs="1"
maxOccurs="1" />
</sequence>
</complexType>
<complexType
name="reactionType">
<sequence>
<any
namespace="##any"
processContents="skip"
minOccurs="1"
maxOccurs="1" />
</sequence>
</complexType>
<!-- ========================================= -->
<!-- -->
<!-- Queries and Lookups -->
<!-- -->
<!-- ========================================= -->
<complexType
name="queryType" />
<element
name="query"
type="iris:queryType"
abstract="true" />
<complexType
name="lookupEntityType" >
<attribute
name="registryType"
type="anyURI"
use="required" />
<attribute
name="entityClass"
type="token"
use="required" />
<attribute
name="entityName"
type="token"
use="required" />
</complexType>
<!-- ========================================= -->
<!-- -->
<!-- Results -->
<!-- -->
<!-- ========================================= -->
<complexType
name="resultType">
<attribute
name="authority"
use="required"
type="token" />
<attribute
name="resolution"
type="token" />
<attribute
name="registryType"
use="required"
type="anyURI" />
<attribute
name="entityClass"
use="required"
type="token" />
<attribute
name="entityName"
use="required"
type="token" />
<attribute
name="temporaryReference"
default="false"
type="boolean" />
</complexType>
<element
name="result"
type="iris:resultType"
abstract="true" />
<!-- ========================================= -->
<!-- -->
<!-- Errors -->
<!-- -->
<!-- ========================================= -->
<complexType
name="codeType">
<sequence
minOccurs="0"
maxOccurs="unbounded">
<element
name="explanation">
<complexType>
<simpleContent>
<extension
base="string">
<attribute
use="required"
name="language"
type="language" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
</complexType>
<element
name="genericCode"
type="iris:codeType"
abstract="true" />
<!-- ========================================= -->
<!-- -->
<!-- Entity References and -->
<!-- Search Continuations -->
<!-- -->
<!-- ========================================= -->
<complexType
name="entityType">
<sequence>
<element
name="displayName"
minOccurs="0"
maxOccurs="unbounded">
<complexType>
<simpleContent>
<extension
base="string">
<attribute
name="language"
use="required"
type="language" />
</extension>
</simpleContent>
</complexType>
</element>
</sequence>
<attribute
name="authority"
use="required"
type="token" />
<attribute
name="resolution"
type="token" />
<attribute
name="registryType"
use="required"
type="anyURI" />
<attribute
name="entityClass"
use="required"
type="token" />
<attribute
name="entityName"
use="required"
type="token" />
<attribute
name="referentType"
use="required"
form="qualified"
type="iris:referentTypeType" />
<attribute
name="temporaryReference"
default="false"
type="boolean" />
<attribute
name="bagRef"
type="IDREF" />
</complexType>
<element
name="entity"
type="iris:entityType" />
<simpleType
name="referentTypeType">
<union
memberTypes="QName iris:anyLiteralType" />
</simpleType>
<simpleType
name="anyLiteralType">
<restriction
base="string">
<enumeration
value="ANY" />
</restriction>
</simpleType>
<complexType
name="searchContinuationType">
<sequence>
<element ref="iris:query" />
</sequence>
<attribute
name="bagRef"
type="IDREF" />
<attribute
name="authority"
type="token"
use="required" />
<attribute
name="resolution"
type="token" />
</complexType>
<element
name="searchContinuation"
type="iris:searchContinuationType" />
<!-- ========================================= -->
<!-- -->
<!-- Bags -->
<!-- -->
<!-- ========================================= -->
<complexType
name="bagsType">
<sequence>
<element
name="bag"
minOccurs="1"
maxOccurs="unbounded">
<complexType>
<complexContent>
<extension
base="iris:bagType">
<attribute
use="required"
name="id"
type="ID" />
</extension>
</complexContent>
</complexType>
</element>
</sequence>
</complexType>
<complexType
name="bagType">
<sequence>
<any
namespace="##any"
processContents="skip"
minOccurs="1"
maxOccurs="1" />
</sequence>
</complexType>
<!-- ========================================= -->
<!-- -->
<!-- Derived Results for use with all -->
<!-- registry types. -->
<!-- -->
<!-- ========================================= -->
<!-- -->
<!-- See Also -->
<!-- -->
<element
name="seeAlso"
type="iris:entityType" />
<!-- -->
<!-- Service Identification -->
<!-- -->
Figure 8
7. The IRIS URI ✨
okay so the IRIS URI has a VERY rigid structure 💅 every single one has the same fields, which is why it looks so similar to users 🫶
but it's also super flexible 🦋 because it lets different methods be used to find servers, and it allows multiple transports (with BEEP being the default) 🔥
7.1. URI Definition 🎀
an IRIS URI [6] basically looks like this:
iris:<registry>/<resolution>/<authority>/<class>/<name>here's the full ABNF [11], which pulls in some values from RFC 2396 [6] and RFC 2732 [15] 🧚
iris-uri = scheme ":" registry-urn "/"
[ resolution-method ] "/" authority
[ "/" entity-class "/" entity-name ]
scheme = "iris"
authority = // as specified by RFC2396
registry-urn = // as specified by IRIS
resolution-method = *(unreserved | escaped)
entity-class = *(unreserved | escaped)
entity-name = *(unreserved | escaped)
unreserved = // as specified by RFC2396
escaped = // as specified by RFC2396an IRIS URI MUST NOT be a relative URI, no exceptions 🙅♀️ and the resolution method, entity class, and entity name MUST be of the UTF-8 [12] character set, encoded with "application/x-www-form-urlencoded" as specified by URL_ENC [14] 💖
if the entity-class and entity-name components aren't specified, the defaults "iris" and "id" MUST be implied ✨ so for example, iris:dreg1//com is interpreted as iris:dreg1//com/iris/id 🍓
and if the resolution-method isn't specified, the default is the direct resolution method from Section 7.3.2 💜
7.2. Transport Specific Schemes 🦋
the "iris" scheme name is not tied to any application transport 🌸 the URI resolution process MAY figure out the application transport, and direct resolution (Section 7.3.2) is an example of that. it uses the steps in Section 7.3.3 to pick the transport 🔍
a mapping between an application transport and IRIS MAY define a scheme name that signals its use, with the semantics of the IRIS URI 🌈
here are the rules for picking which application transport to use 👑
- If an application transport specific scheme name is present, the application transport it signifies SHOULD be used if possible.
- If a client has a preferred transport and the resolution process allows for its use, the client MAY use that application transport.
- Otherwise, the default application transport specified by IRIS-BEEP [1] MUST be used.
7.3. URI Resolution 🔥
7.3.1. Registry Dependent Resolution 🌈
the interpretation and resolution of the authority component of an IRIS URI may be altered by specifying a resolution-method in the URI 🧚 if no resolution-method component is in the URI, the default is the direct resolution method (see Section 7.3.2) 💅
alternate resolution methods MAY be specified by registry types 🦋 and their identifiers MUST conform to the ABNF in Section 7.1 ✨
7.3.2. Direct Resolution ✨
Okay so direct resolution is the one where the authority part of an IRIS URI can only be one of four things 💅: a domain name, a domain name plus a port number, an IP address, or an IP address plus a port number. The authority component tells you which server (or group of servers) is in charge of a domain according to DNS records (Section 7.3.3) when you've given a domain. If you gave an IP address instead, that's the exact server that gets asked 🎀
Here's how the rules go:
- If the authority component is a domain name with a port number, the way RFC 2396 describes it, the domain name gets turned into an IP address using an A or AAAA record in the DNS 🌸
- If the authority component is just a domain name, the service/transport location process (Section 7.3.3) runs first. If that process comes back empty, the DNS gets queried for the A or AAAA RRs for that domain name, and the port number used is the well-known port of the transport, per Section 7.2 🦋
- If the authority component is an IP address, the DNS is NOT queried and the IP address is used directly 🙈. If a port number is there, it gets used directly too. If not, the port number is the well-known port of the transport, per Section 7.2.
Heads up bestie: if you're writing an IPv6 address in the authority component, it MUST conform to RFC 2732 [15]. No skipping this one 😭
7.3.3. Transport and Service Location 🧚
So the direct resolution method (Section 7.3.2) uses the profiled version of the NAPTR and SRV resource records defined in S-NAPTR [10]. Those figure out where a set of servers for a given service lives, plus which transports they might be using 🔥. Any resolution method that doesn't make explicit use of direct resolution is RECOMMENDED to use S-NAPTR [10] in whatever process it does define, so it's giving consistency 💜.
S-NAPTR [10] needs an application service label. The direct resolution method (Section 7.3.2) uses the abbreviated form of the registry URN as its application service label. Other resolution methods MAY specify their own application service labels ✨.
Check Appendix A for sample uses of S-NAPTR 📖.
7.4. IRIS URI Examples 🎀
Here are some IRIS URIs and what they actually mean, bestie 👑:
iris:dreg1//example.com/domain/example.com- Finds a server authoritative for "example.com" according to the rules of direct resolution (Section 7.3.2).
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
iris:dreg1//example.com- Finds a server authoritative for "example.com" according to the rules of direct resolution (Section 7.3.2).
- The server is asked for "id" in the "iris" index, or entity class, of the "dreg1" registry.
iris:dreg1//com/domain/example.com- Finds a server authoritative for "com" according to the rules of direct-resolution (Section 7.3.2).
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
iris:dreg1//192.0.2.1:44/domain/example.com- Following the rules of direct-resolution (Section 7.3.2), the server at IP address 192.0.2.1 on port 44 is queried by using BEEP.
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
iris.lwz:dreg1//192.0.2.1:44/domain/example.com- Following the rules of direct-resolution (Section 7.3.2), the server at IP address 192.0.2.1 on port 44 is queried by using a lightweight application transport.
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
iris.beep:dreg1//com/domain/example.com- Finds a server authoritative for "com" according to the rules of direct-resolution (Section 7.3.2).
- Uses the BEEP application transport.
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
iris:dreg1/bottom/example.com/domain/example.com- Finds a server authoritative for "example.com" according to the rules of the resolution method 'bottom' as defined by the registry type urn:ietf:params:xml:ns:dreg1.
- The application transport used is determined by the 'bottom' resolution method.
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
iris.beep:dreg1/bottom/example.com/domain/example.com- Finds a server authoritative for "example.com" according to the rules of the resolution method 'bottom' as defined by the registry type urn:ietf:params:xml:ns:dreg1.
- Uses the BEEP application transport.
- The server is asked for "example.com" in the "domain" index, or entity class, of the "dreg1" registry.
8. Checklists 💖
8.1. Registry Definition Checklist 🌈
Specifications of registry types MUST include the following explicit definitions:
- Formal XML syntax deriving from the IRIS XML.
- An identifying registry URN.
- Any registry specific resolution methods.
- A registration of the abbreviated registry URN as an application service label for compliance with S-NAPTR [10]. Note that this is a different IANA registry than the registry type URN IANA registry.
- A list of well-known entity classes.
- A statement regarding the case sensitivity of the names in each entity class.
8.2. Transport Mapping Checklist 🦋
Specifications of transport mappings MUST include the following explicit definitions:
- A URI scheme name specific to the transport.
- An application protocol label for compliance with S-NAPTR [10]. See Section 7.3.3. Note that although this is a different IANA registry than the URI scheme name IANA registry, it is RECOMMENDED that they be the same string of characters.
- The set of allowable character set encodings for the exchange of XML (see Section 9).
- The set of security mechanisms.
9. Internationalization Considerations 🌸
IRIS is represented in XML, and XML processors are obliged to recognize both UTF-8 and UTF-16 [12] encodings 🌍. XML gives you ways to use other character encodings through the "encoding" attribute in the <xml> declaration. If that attribute is missing, or there's no byte order mark (BOM), the default is UTF-8 [13] encoding. So for compatibility reasons, and per RFC 2277 [16], use of UTF-8 [13] is RECOMMENDED with IRIS 💅.
The complete list of character set encoding identifiers is maintained by IANA at [21].
The application-transport layer MUST define a common set of character set encodings to be understood by both client and server.
Localization of internationalized strings may need extra info from the client 🫶. Entity definitions SHOULD use the "language" type defined by XML_SD [4] to help clients with localization. See Section 4.3.7.3 for an example.
10. IANA Considerations 📋
This document uses a proposed XML namespace and schema registry specified in XML_URN [9]. So the following registration information is provided for the IANA:
- URN/URI:
urn:ietf:params:xml:ns:iris1
- Contact:
Andrew Newton <andy@hxr.us>Marcos Sanz <sanz@denic.de>
- XML:
- The XML Schema specified in Section 6
11. Security Considerations 🔥
Bestie, this section is SERIOUS 😭 Read it all!
The IRIS XML layer provides no authentication or privacy facilities of its own. It relies on the application-transport layer for all of these abilities. Application-transports should explicitly define their security mechanisms (see Section 8.2).
Referral IRIS registry results may contain entity lookups and search continuations that result in a client query operation against another registry service. Clients SHOULD NOT use authentication credentials and mechanisms subject to replay attacks to conduct subsequent entity lookups and search continuations 💀.
12. References 📚
12.1. Normative References 💜
- [1] Newton, A. and M. Sanz, "Using the Internet Registry Information Service (IRIS) over the Blocks Extensible Exchange Protocol (BEEP)", RFC 3983, January 2005.
- [2] World Wide Web Consortium, "Extensible Markup Language (XML) 1.0", W3C XML, February 1998,
<http://www.w3.org/TR/1998/REC-xml-19980210>. - [3] World Wide Web Consortium, "Namespaces in XML", W3C XML Namespaces, January 1999,
<http://www.w3.org/TR/1999/REC-xml-names-19990114>. - [4] World Wide Web Consortium, "XML Schema Part 2: Datatypes", W3C XML Schema, October 2000,
<http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/>. - [5] World Wide Web Consortium, "XML Schema Part 1: Structures", W3C XML Schema, October 2000,
<http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/>. - [6] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
- [7] Moats, R., "URN Syntax", RFC 2141, May 1997.
- [8] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [9] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
- [10] Daigle, L. and A. Newton, "Domain-based Application Service Location Using SRV RRs and the Dynamic Delegation Discovery Service (DDDS)", RFC 3958, January 2005.
- [11] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997.
- [12] The Unicode Consortium, "The Unicode Standard, Version 3", ISBN 0-201-61633-5, 2000,
<The Unicode Standard, Version 3>. - [13] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003.
- [14] Connolly, D. and L. Masinter, "The 'text/html' Media Type", RFC 2854, June 2000.
- [15] Hinden, R., Carpenter, B., and L. Masinter, "Format for Literal IPv6 Addresses in URL's", RFC 2732, December 1999.
- [16] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998.
12.2. Informative References 🦋
- [17] Newton, A., "Cross Registry Internet Service Protocol (CRISP) Requirements", RFC 3707, February 2004.
- [18] Newton, A. and M. Sanz, "IRIS: A Domain Registry (dreg) Type for the Internet Registry Information Service (IRIS)", RFC 3982, January 2005.
- [19] Daigle, L., "WHOIS Protocol Specification", RFC 3912, September 2004.
- [20] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC 3080, March 2001.
URIs 🔗
Appendix A. S-NAPTR and IRIS Uses ✨
A.1. Example of S-NAPTR with IRIS ✨
okay so this section shows an example of how S-NAPTR [10] gets used by IRIS 💖 we've got two registry types, REGA and REGB, and two IRIS application transports, iris-a and iris-b. with all that, S-NAPTR gives you three things:
- a way for an operator to split the set of servers running REGA from the set of servers running REGB. so basically, the operator can pull apart the servers serving up REGA data from the ones serving up REGB data 🎀
- a way for an operator to tell apart the servers running iris-a from the servers running iris-b. so the operator can separate the servers running the iris-a protocol that serve REGA and REGB data from the servers running the iris-b protocol that serve REGA and REGB data 🦋
- a way for an operator to pick which set of the servers above they run themselves, and which set they hand off to another operator 👑
to get feature one going, the operator puts this in their DNS zone:
example.com.
;; order pref flags service re replacement
IN NAPTR 100 10 "" "REGA:iris-a:iris-b" "" rega.example.com
IN NAPTR 100 10 "" "REGB:iris-a:iris-b" "" regb.example.comfor feature two, the operator then adds this to their DNS zone:
rega.example.com.
;; order pref flags service re replacement
IN NAPTR 100 10 "s" "REGA:iris-a" "" _iris-a._udp.example.com
regb.example.com.
IN NAPTR 100 10 "s" "REGA:iris-b" "" _iris-b._tcp.example.com
_iris-a._udp.example.com.
;; pref weight port target
IN SRV 10 0 34 big-a.example.com.
IN SRV 20 0 34 small-a.example.com.
_iris-b._tcp.example.com.
;; pref weight port target
IN SRV 10 0 34 big-b.example.com.
IN SRV 20 0 34 small-b.example.com.and finally, an operator might want to keep running the REGA services while handing the REGB services off to somebody else 🌸 here's how that looks:
example.com.
;; order pref flags service re replacement
IN NAPTR 100 10 "" "REGA:iris-a:iris-b" "" rega.example.com
IN NAPTR 100 10 "" "REGB:iris-a:iris-b" "" somebodyelse.comor the operator could run REGB services under the iris-a protocol/transport and hand the REGB services under the iris-b protocol/transport to somebody else. that's a whole other vibe 🧚
example.com.
;; order pref flags service re replacement
IN NAPTR 100 10 "" "REGB:iris-a:iris-b" "" regb.example.com
IN NAPTR 100 10 "s" "REGB:iris-a" "" _iris-a._udp.example.com
IN NAPTR 100 10 "s" "REGB:iris-b" "" _iris-b._tcp.somebodyelse.com
_iris-a._udp.example.com.
;; pref weight port target
IN SRV 10 0 34 big-a.example.com.
IN SRV 20 0 34 small-a.example.com.ngl, this last example is possible, but it's probably not advisable. keeping the data in sync between example.com and somebodyelse.com is operationally messy 😭 it's included just to show what can be done, not what you should do.
A.2. Using S-NAPTR for Cohabitation 🫶
so with the examples from Appendix A.1 in mind, S-NAPTR could be part of a transition plan for protocols that have to live side by side while solving the problems of CRISP [17] 💅
for instance, domain information could be given the application service label "DREG1". then the service field of an S-NAPTR compliant NAPTR record could read:
"DREG1:whois:iris-beep"that service field says the domain data, as defined by CRISP, is available through both the iris-beep protocol and the whois protocol. and the whois application protocol label refers to RFC 954 [19] 🍓
Appendix B. IRIS Design Philosophy 🌈
okay bestie, past all the nitty-gritty about the bits zooming across the wire, there are some bigger-picture reasons IRIS exists at all. this section gives it a shot 💜
B.1. The Basic Premise
IRIS was built as a directory service for public-facing registries of Internet resources. the core idea goes like this:
- A client should be able to look up any single piece of data from any type of registry. this lookup should use a straightforward, consistent way to find the registry, and it should boil down to one hit on a single data index in the registry.
- Anything more, like searching up and down the DNS tree to find the registry or searching across multiple indexes in a registry, needs a client that already knows how the data relates to each other inside a registry 🙈
so, IRIS does the following:
- It specifies the basic schema language that every registry uses to define its schemas.
- It provides the basic framework for a registry to refer to an entity in another type of registry.
and, therefore, IRIS does not do the following:
- It does not specify a common query language across all types of registries. a common query language forced across several registry types usually means a server operator ends up turning off certain functions just to keep performance acceptable, and then you're left with a common query language that doesn't commonly work 💀
- It does not impose any relationship between sets of data in any type of registry, such as requiring a tree. there are lots of kinds of Internet resources, and they don't all relate to their data the same way. when a common relationship doesn't fit naturally, forcing one is more of a problem than a perk ✨
B.2. The Lure of a Universal Client 🌸
the whole design premise of IRIS means that, for directory services, there's no such thing as a universal client (or if there is one, people call it the "web browser") 😂
for IRIS, the nearest thing to a universal client is one that can "look up" data and display it in a basic way. if a client wants to "search" or show data in a truly user-friendly way, it has to know specifically what type of data it's pulling back 🦋
trying to give a universal client a common query language doesn't really help either. a common query language might work for one specific problem domain, but then the user needs expertise in both the query language and that domain. in the end, you usually wind up with a client built for that one domain anyway, stuck translating what the user wants and dealing with the lowest-common-denominator parts of the query language 🙃
B.3. Server Considerations 🛡️
like we said above, IRIS was designed for the directory service needs of public-facing registries. in that setting, some parts of more generalized directory services get in the way, since the environment doesn't have the same control and safety considerations as a managed network 🚧
for example, a common query language gives great flexibility to the power user and the abusive user alike. an abusive user could easily send a query across multiple indexes with partial values. a query like that has no real use other than causing denial of service to other users 😤 to fight that, a service operator has to restrict the kinds of queries that hurt overall performance, and doing that cancels out the benefit of a common query language.
another server performance thing is the lack of a required data relationship. since sets of data often relate in different ways, a one-size-fits-all approach just doesn't work for every type of registry. plus, public-facing services tend to have service level requirements that can't reasonably be met by converting complete data stores from their native format into a format that enforces an artificial set of relationships 🍓
to deal with these issues, operators of public-facing services often build their own custom query parsers and back-end data stores. but doing that makes you question whether a generalized directory service is worth using at all 🤔
last but not least, IRIS is built on a set of standard technology layers. that lets service operators swap out components to fit their particular environment 🔧
B.4. Lookups, Searches, and Entity Classes 🔍
IRIS supports both lookups and searches. the difference between them is basically this:
A "lookup" is a single query with a discrete value on a single index. Anything more, such as partial value queries, queries across multiple indexes, or multiple queries to a single index is a "search".
lookups happen through the defined query <lookupEntity>. that query names a discrete name, called the entity name, to be looked up in a single index, called the entity class. so implementations can think of a type of registry as being made up of multiple indexes, one for each defined entity class 💜
there are no standard searches in IRIS. each type of registry defines its own set of searches 🌈
B.5. Entities References, Search Continuations, and Scope ✨
because of how it affects client behavior, and the side effects that behavior can have on servers, IRIS draws a clear line between entity references (<entity>) and search continuations (<searchContinuation>). this isn't an add-on. it's a fundamental core of the protocol 💅
the difference matters a lot to a client:
"Go look over there and you will find what you seek." "Go look over there and you may find what you seek, or you may find some other stuff, or you may find nothing."
finally, IRIS makes no assumptions about the relationship of data in a registry and places no requirements on it. that also covers data of the same registry type spread across multiple authority areas. so IRIS sets no requirements on the scope of entity references or search continuations. the scope is decided by what the registry type needs and by what the registry type allows a service operator to do 🎀
Appendix C. Acknowledgments 💖
huge thanks to Leslie Daigle, whose skillful debate tactics made the terminology in this document for namespaces and namespaces of namespaces way clearer. before that, it was a total mess 🙌 Leslie also gave great insight into the details of URIs, URNs, and NAPTR/SRV resource records 🫶
a bunch of technical complexities were shown to be unnecessary by David Blacka, and they've been removed. his IRIS implementation also helped smooth out the rougher edges 👑
Authors' Addresses 🦋
Andrew L. Newton
VeriSign, Inc.
21345 Ridgetop Circle
Sterling, VA 20166
USA
Phone: +1 703 948 3382
EMail: anewton@verisignlabs.com; andy@hxr.us
URI: http://www.verisignlabs.com/
Marcos Sanz
DENIC eG
Wiesenhuettenplatz 26
D-60329 Frankfurt
Germany
EMail: sanz@denic.de
URI: http://www.denic.de/Full Copyright Statement ✨
Copyright (C) The Internet Society (2005). 💖
This doc is subject to the rights, licenses and restrictions in BCP 78. Unless it says otherwise there, the authors keep all their rights. 🎀
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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.
Basically, it's all provided "as is" 🫶 and the contributor, whoever they're representing or sponsored by, the Internet Society, and the IETF all say no to warranties. That covers not infringing anyone's rights, plus implied merchantability and fitness for a particular purpose. 💅
Intellectual Property 🦋
Okay so the IETF doesn't take a side on whether any IPR claims are valid or how far they reach, and it doesn't say whether licenses are available either. It also hasn't checked for any of those rights itself 🙈 If you want the IETF's rules on rights in its documents, check BCP 78 and BCP 79.
Copies of IPR disclosures sent to the IETF Secretariat are on the IETF's online IPR repository at http://www.ietf.org/ipr. You can also find any licensing assurances there, plus results from attempts to get a general license or permission for implementers or users to use the proprietary rights. 🔥
The IETF invites anyone to flag any copyrights, patents, patent applications or other proprietary rights that might cover technology needed to implement this standard. Send that info to ietf-ipr@ietf.org. 🌸
Acknowledgement 🌈
Funding for the RFC Editor function is currently provided by the Internet Society. 👑
📦 where this page comes from
- ietf: rfc3981 2005-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms