RFC 4991

A Common Schema for Internet Registry Information Service Transfer Protocols

📅 published August 2007, from ietf

RFC 4991 💖 Part 1 of 3

okay bestie, let's get into it 🦋 RFC 4991 is called "A Common Schema for Internet Registry Information Service Transfer Protocols" and it's written by A. Newton from VeriSign, Inc. It was published in August 2007 and it's on the Standards Track, so this is a real internet standard 💅 It came out of the Network Working Group. Heads up: its header doesn't list anything it obsoletes or updates, so it's standing on its own 👑

Status of This Memo 📜

this is a standards track protocol for the internet community, and it's begging for discussion and suggestions to make it better 🌸 For the current 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 (C) The IETF Trust (2007)

Abstract ✨

So this doc describes an XML Schema that Internet Registry Information Service (IRIS) application transfer protocols can use when they share common characteristics 🎀 It covers common info about the transfer protocol, like the version, supported extensions, and supported security mechanisms 🔐

Table of Contents 🧚

1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  2
2.  Document Terminology . . . . . . . . . . . . . . . . . . . . .  2
3.  Formal XML Syntax  . . . . . . . . . . . . . . . . . . . . . .  3
4.  Version Information  . . . . . . . . . . . . . . . . . . . . .  6
5.  Size Information . . . . . . . . . . . . . . . . . . . . . . .  7
6.  Authentication Success Information . . . . . . . . . . . . . .  8
7.  Authentication Failure Information . . . . . . . . . . . . . .  8
8.  Other Information  . . . . . . . . . . . . . . . . . . . . . .  9
9.  Internationalization Considerations  . . . . . . . . . . . . .  9
10. IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 10
  10.1.  XML Namespace URN Registration  . . . . . . . . . . . . . 10
11. Security Considerations  . . . . . . . . . . . . . . . . . . . 10
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
  12.1.  Normative References  . . . . . . . . . . . . . . . . . . 11
  12.2.  Informative References  . . . . . . . . . . . . . . . . . 11
Appendix A.  Contributors  . . . . . . . . . . . . . . . . . . . . 12

1. Introduction ✨

okay so IRIS [8] has two transfer protocols, LWZ (lightweight using compression) [9] and XPC (XML pipelining with chunks) [10], and they share common negotiation mechanisms 🍓 Both of them need the server to give clients rich status info during negotiation. Usually that info is too complex to squeeze into simple bit fields and length-specified octet sequences 🙈 So this doc defines an XML Schema for that rich status info and explains how to use conformant XML to carry it 💅

This doc defines five types of info used when negotiating protocol capabilities: version, size, authentication success, authentication failure, and other info 💖 Version info negotiates the versions and extensions of the transfer protocol, the application operations protocol, and the data models those app operations use. Size info shows request and response size capabilities and errors 📦 Authentication success and failure info tells you how an authentication action turned out 🔐 Other info can also be sent, and it's usually the result of an error that can't be fixed through defined protocol behavior 💀

Here's an example. When a connection starts, a server can send version info telling the client which data models and security mechanisms it supports 🧚 The client then responds. Like, the client might not recognize any of the server's data models, so it closes the connection 😭 Or it recognizes the data models and security mechanisms, so it starts setting up a security mechanism with the server before querying data using a data model it knows 👑

Both LWZ [9] and XPC [10] show examples of how to use the XML Schema defined here 🌈

2. Document Terminology 📖

Heads up, the super-serious capital words you'll see are key words that mean exactly what RFC 2119 [6] says they mean 🔥 In this document, "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" get read that way.

3. Formal XML Syntax 🎀

This is the XML Schema used to define transfer protocol status information. Check these specs out too: [2], [3], [4], [5] 🫶 And if anyone wants to update or change this schema, they need a document that UPDATES or OBSOLETES this one.

<?xml version="1.0"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:iristrans="urn:ietf:params:xml:ns:iris-transport"
        targetNamespace="urn:ietf:params:xml:ns:iris-transport"
        elementFormDefault="qualified" >

<annotation>
  <documentation>
    A schema for describing status information
    for use by multiple transfer protocols.
  </documentation>
</annotation>

<element name="versions">
  <complexType>
    <sequence>
      <element name="transferProtocol" maxOccurs="unbounded">
        <complexType>
          <sequence>
            <element name="application" minOccurs="0"
              maxOccurs="unbounded">
              <complexType>
                <sequence>
                  <element name="dataModel" minOccurs="0"
                    maxOccurs="unbounded">
                    <complexType>
                      <attribute name="protocolId" type="token"
                        use="required" />
                      <attribute name="extensionIds"
                        type="normalizedString" />
                    </complexType>
                  </element>
                </sequence>
                <attribute name="protocolId" type="token"
                  use="required" />
                <attribute name="extensionIds"
                  type="normalizedString" />
              </complexType>
            </element>
          </sequence>
          <attribute name="protocolId" type="token" use="required"

            />
          <attribute name="extensionIds" type="normalizedString" />
          <attribute name="authenticationIds"
            type="normalizedString" />
          <attribute name="responseSizeOctets"
            type="positiveInteger" />
          <attribute name="requestSizeOctets"
            type="positiveInteger" />
        </complexType>
      </element>
    </sequence>
  </complexType>
</element>

<element name="size">
  <complexType>
    <sequence>
      <element name="request"
        minOccurs="0"
        type="iristrans:octetsType" />
      <element name="response"
        minOccurs="0"
        type="iristrans:octetsType" />
    </sequence>
  </complexType>
</element>

<complexType name="octetsType">
  <choice>
    <element name="exceedsMaximum">
      <complexType/>
    </element>
    <element name="octets" type="positiveInteger" />
  </choice>
</complexType>

<element name="authenticationSuccess">
  <complexType>
    <sequence>
      <element name="description" minOccurs="0"
        maxOccurs="unbounded">
        <complexType>
          <simpleContent>
            <extension base="string">
              <attribute name="language" type="language"
                use="required"/>
            </extension>
          </simpleContent>
        </complexType>
      </element>
      <element name="data" minOccurs="0" maxOccurs="1"
        type="base64Binary"/>
    </sequence>
  </complexType>
</element>

<element name="authenticationFailure">
  <complexType>
    <sequence>
      <element name="description" minOccurs="0"
        maxOccurs="unbounded">
        <complexType>
          <simpleContent>
            <extension base="string">
              <attribute name="language" type="language"
                use="required"/>
            </extension>
          </simpleContent>
        </complexType>
      </element>
    </sequence>
  </complexType>
</element>

<element name="other">
  <complexType>
    <sequence>
      <element name="description" minOccurs="0"
        maxOccurs="unbounded">
        <complexType>
          <simpleContent>
            <extension base="string">
              <attribute name="language" type="language"
                use="required"/>
            </extension>
          </simpleContent>
        </complexType>
      </element>
    </sequence>
    <attribute type="token" name="type" use="required"/>
  </complexType>
</element>

</schema>

4. Version Information ✨

Okay bestie, the <versions> element is where you spill the tea on version info 🫶 It describes the transfer protocol, the application protocol, and the data models the application protocol uses. Main character energy 💅

The <versions> element has one or more <transferProtocol> child elements. <transferProtocol> elements have zero or more <application> child elements, and <application> elements have zero or more <dataModel> elements. Each of these element types has a protocolId attribute that identifies the protocol it represents, plus an optional extensionIds attribute that identifies the protocol extensions it supports. 🦋

During capabilities negotiation, both sides are expected to recognize the protocolId value of the <transferProtocol> element and at least one of the <application> and <dataModel> elements. If the negotiation lands in a spot where that isn't possible, an error SHOULD be given and communication ended. 💀 It is not expected that each side recognizes the extensionIds values, but unrecognized extensionIds values MUST be ignored. Not me being chill about extensions 😌

Also, <transferProtocol> has optional authenticationIds, responseSizeOctets, and requestSizeOctets attributes. authenticationIds identifies the authentication mechanisms the transfer protocol supports. responseSizeOctets describes the maximum response size in octets the server will give, and requestSizeOctets describes the maximum request size in octets the server will accept. 🌸

The protocol, extension, and authentication mechanism identifiers are of no specific type, and this document defines none. Specifications using this XML Schema MUST define the identifiers for use with the <versions> element and its children. 📝

Counting octets is kinda messy 🙈 Different transfer protocols count them in different ways. Some only need to count the octets of the data being transferred, while others also have to account for the extra octets they use to move that data. Specifications using this XML Schema MUST describe how these octet counts are calculated. 🧮

Here's some example XML describing version information 🎀

<versions xmlns="urn:ietf:params:xml:ns:iris-transport">
  <transferProtocol protocolId="iris.lwz"
    authenticationIds="PLAIN EXTERNAL">
    <application protocolId="urn:ietf:params:xml:ns:iris1"
      extensionIds="http://example.com/SIMPLEBAG">
      <dataModel protocolId="urn:ietf:params:xml:ns:dchk1"/>
      <dataModel protocolId="urn:ietf:params:xml:ns:dreg1"/>
    </application>
  </transferProtocol>
</versions>

Version Information Example

5. Size Information 📏

The <size> element is how a server tells a client that a request has blown past a negotiated size (<request>), or that a response is going to be bigger than a negotiated size (<response>). 😭

A server can signal one of two size conditions by including one of these child elements:

  • <exceedsMaximum>: this child element just says the size went over the negotiated size.
  • <octets>: this child element says the size went over the negotiated size and gives a number. If the parent is a <request> element, that number is the maximum for a request. If the parent is a <response> element, that number is how many octets are needed to provide the response.

Counting octets is kinda messy 🙈 Different transfer protocols count them in different ways. Some only need to count the octets of the data being transferred, while others also have to account for the extra octets they use to move that data. Specifications using this XML Schema MUST describe how these octet counts are calculated. 🧮

Here's some example XML describing size information 🦋

<size xmlns="urn:ietf:params:xml:ns:iris-transport">
  <response>
    <octets>1211</octets>
  </response>
</size>

Size Information Example

6. Authentication Success Information 🎉

The <authenticationSuccess> element says a client has successfully authenticated to a server. It can also come with text that may be shown to a user about that successful authentication, using child <description> elements. 🔥

Each <description> element MUST have a language attribute that describes the language of the content of the <description> element. Clients aren't expected to stitch multiple descriptions together, so servers MUST NOT provide multiple <description> elements with the same language descriptor. 🙅‍♀️

Finally, extra security data can be sent back with the authentication success message using the <data> element. The content of this element is of the base64Binary simple type. 🔐

Here's some example XML describing authentication success information 💖

<authenticationSuccess
  xmlns="urn:ietf:params:xml:ns:iris-transport">
  <description language="en">
    user 'bob' authenticates via password
  </description>
</authenticationSuccess>

Authentication Success Example

7. Authentication Failure Information 💔

The <authenticationFailure> element says a client has failed to properly authenticate to a server. Along with that, it can include text for a user about the failure, using child <description> elements. 😬

Each <description> element MUST have a language attribute that describes the language of the content of the <description> element. Clients aren't expected to stitch multiple descriptions together, so servers MUST NOT provide multiple <description> elements with the same language descriptor. 🫶

Here's some example XML describing authentication failure information 🌈

<authenticationFailure
  xmlns="urn:ietf:params:xml:ns:iris-transport">
  <description language="en">
    please consult your admin if you have forgotten your password
  </description>
</authenticationFailure>

Authentication Failure Example

8. Other Information 🧚

The <other> element carries status information that may need a human to interpret it so it actually makes sense. 🤓 This element has a required type attribute, which holds an identifier for the nature of the information. This document doesn't define any identifiers for that attribute, but the goal is that these identifiers are well-known, so clients can take different classes of action based on what's in the attribute. Because of that, specifications making use of this XML Schema MUST define these identifiers. 📚

The <other> element may have zero or more <description> elements. Each <description> element MUST have a language attribute that describes the language of the content of the <description> element. Servers can use these child elements to share text with clients about the class (or type) of status information the <other> element is specifying. Clients aren't expected to stitch multiple descriptions together, so servers MUST NOT provide multiple <description> elements with the same language descriptor. 🙌

Here's some example XML describing other information ✨

<other xmlns="urn:ietf:params:xml:ns:iris-transport" type="system">
  <description language="en">unavailable, come back
    later</description>
</other>

Other Information Example

9. Internationalization Considerations 🌍

XML processors are obliged to recognize both UTF-8 and UTF-16 [1] encodings. XML also has mechanisms to identify and use other character encodings. Application transfer protocols MUST define which additional character encodings, if any, are allowed in the use of the XML defined in this document. 🗣️

10. IANA Considerations 🗂️

10.1. XML Namespace URN Registration

This document uses the XML namespace and schema registry specified in XML_URN [7]. So IANA has made the following registrations:

  • XML Namespace URN/URI:
    • urn:ietf:params:xml:ns:iris-transport
  • Contact:
    • Andrew Newton <andy@hxr.us>
  • XML:
    • None
  • XML Schema URN/URI:
    • urn:ietf:params:xml:schema:iris-transport
  • Contact:
    • Andrew Newton <andy@hxr.us>
  • XML:
    • The XML Schema specified in Section 3

11. Security Considerations 🚨

Transfer protocols using XML that conforms to the XML Schema in this document, and that also offer security properties like authentication and confidentiality, SHOULD offer an initial message from the server to the client using the <versions> element. This <versions> element SHOULD contain all relevant authentication identifiers in its 'authenticationId' attribute. The whole point of that initial message is to help thwart downgrade attacks. 🛡️💀 This one is serious, bestie, so don't skip it!

12. References 📖

12.1. Normative References

12.2. Informative References

  • [8] Newton, A. and M. Sanz, "IRIS: The Internet Registry Information Service (IRIS) Core Protocol", RFC 3981, January 2005.
  • [9] Newton, A., "A Lightweight UDP Transfer Protocol for the Internet Registry Information Service", RFC 4993, August 2007.
  • [10] Newton, A., "XML Pipelining with Chunks for the Internet Registry Information Service", RFC 4992, August 2007.

Appendix A. Contributors 🌟

Substantive contributions to this document have been provided by the members of the IETF's CRISP Working Group, especially Robert Martin-Legene, Milena Caires, and David Blacka. Thank you, queens 👑

Author's Address 💌

Andrew L. Newton
VeriSign, Inc.
21345 Ridgetop Circle
Sterling, VA  20166
USA

Phone: +1 703 948 3382
EMail: andy@hxr.us
URI:   http://www.verisignlabs.com/

Copyright (C) The IETF Trust (2007).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain 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, THE IETF TRUST 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.

Intellectual Property ✨

okay so this part is about who owns what 💅 the IETF is basically like "we are NOT saying whether any patents or rights apply to the tech in this doc, and we didn't go hunting for them either" 🙈 it's giving "not our problem, bestie" but make it legal. if you want the rules for rights in RFC documents, check out BCP 78 and BCP 79 🧚

copies of IPR disclosures sent to the IETF Secretariat, plus any promised licenses, or the results of trying to get a general license or permission for implementers or users to use proprietary rights, can be found on the IETF online IPR repository at http://www.ietf.org/ipr 🔗

and if you're someone who thinks you own a copyright, patent, patent application, or other proprietary right that might cover tech needed to implement this standard, the IETF wants to hear from you 🫶 send that info to them at ietf-ipr@ietf.org 📬

Acknowledgement 🌸

last but not least, the people keeping the RFC Editor function running get their funding from the Internet Society 💜 so shoutout to them for keeping the lights on ✨

📦 where this page comes from