Key-Value Mapping for the Extensible Provisioning Protocol (EPP)
draft-ar-key-value-epp-mapping-01

Abstract

This document describes an Extensible Provisioning Protocol (EPP) extension mapping for the transport of arbitrary data associated with domain names stored in a shared central repository.

Status of this Memo

This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

This Internet-Draft will expire on June 4, 2013.

Table of Contents

1.  Introduction
    1.1.  Conventions Used in This Document
2.  Object Attributes
    2.1.  Key Value Pairs
3.  EPP Command Mapping
    3.1.  EPP Query Commands
        3.1.1.  EPP <check> Command
        3.1.2.  EPP <info> Command
        3.1.3.  EPP <transfer> Command
    3.2.  EPP Transform Commands
        3.2.1.  EPP <create> Command
        3.2.2.  EPP <delete> Command
        3.2.3.  EPP <renew> Command
        3.2.4.  EPP <transfer> Command
        3.2.5.  EPP <update> Command
4.  Formal Syntax
5.  Security Considerations
6.  Normative References
§  Authors' Addresses

1.  Introduction

This document describes an domain mapping for version 1.0 of the Extensible Provisioning Protocol (EPP) that allows for the transport of arbitrary data associated with a domain name.

Servers may require additional information to be associated with domain names to support domain name eligibility requirements, or to support transport of data required for specific operations.

Formal definition of this addtional data presents a costly solution when information accepted by one server is not likely to be accepted by another server. In such cases this extension may present a cost-effective solution without having to implement several extensions to EPP.

1.1.  Conventions Used in This Document

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

"kv-1.0" is used as an abbreviation for "urn:X-ar:params:xml:ns:kv-1.0". The XML namespace prefix "kv" is used, but implementations MUST NOT depend on it and instead employ a proper namespace-aware XML parser and serializer to interpret and output the XML documents.

This document uses ficticous key-values in command and response examples. Servers are required to define their list of acceptable keys and their corresponding values and to publish these requirements to clients using an out-of-band mechanism.

2.  Object Attributes

This extension adds additional elements to the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731]. Only those new elements are described here.

2.1.  Key Value Pairs

Arbitrary data associated with a domain is represented using key-value pairs. Keys identify values, akin to how maps and dictionaries work in programming languages. Lists of related values are grouped together into lists, clearly delineating related information without codifying relationships into key names.

Key-value pairs are expressed using an <item> element that contains the value to be associated with the domain. A mandatory "key" element identifies the value.

Servers SHOULD make available to clients the list of values, and identifying keys, that can be associated with domain objects. Definitions, published using out of band mechanisms, should identify mandatory fields, and restrictions and validations placed on certain values.

3.  EPP Command Mapping

A detailed description of the EPP syntax and semantics can be found in the EPP core protocol specification (Hollenbeck, S., “Extensible Provisioning Protocol (EPP),” August 2009.) [RFC5730]. The command mappings described here are specifically for use in provisioning and managing generic domain extensions via EPP.

3.1.  EPP Query Commands

EPP provides three commands to retrieve object information: <check> to determine if an object is known to the server, <info> to retrieve detailed information associated with an object, and <transfer> to retrieve object transfer status information.

3.1.1.  EPP <check> Command

This extension does not define any extension to the EPP <check> command or response described in the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

3.1.2.  EPP <info> Command

This extension does not add any elements to the EPP <info> command described in the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731]. However, additional elements are defined for the <info> response.

To enable clients to identify the additional information currently associated with a domain object, the <domain:infData> respsonse is extended with a <kv:infData> element that contains the following child elements:

• One or more <kvlist> elements that contain a list of key-value items associated with the domain object, as described in Key Value Pairs (Key Value Pairs). A "name" attribute MUST be present to identify the name of the key-value list.

Example <info> response containing arbitrary key-value pairs

<?xml version="1.0" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <response>
    <result code="1000">
      <msg>Command completed successfully</msg>
    </result>
    <resData>
      <infData xmlns="urn:ietf:params:xml:ns:domain-1.0">
        <name>xn--ls8h.example</name>
        <roid>EXAMPLE1-REP</roid>
        <status s="ok" />
        <registrant>jd1234</registrant>
        <contact type="admin">sh8013</contact>
        <contact type="tech">sh8013</contact>
        <ns>
          <hostObj>ns1.example.com</hostObj>
          <hostObj>ns1.example.net</hostObj>
        </ns>
        <host>ns1.example.com</host>
        <host>ns2.example.com</host>
        <clID>ClientX</clID>
        <crID>ClientY</crID>
        <crDate>1999-04-03T22:00:00.0Z</crDate>
        <upID>ClientX</upID>
        <upDate>1999-12-03T09:00:00.0Z</upDate>
        <exDate>2005-04-03T22:00:00.0Z</exDate>
        <trDate>2000-04-08T09:00:00.0Z</trDate>
        <authInfo>
          <pw>2fooBAR</pw>
        </authInfo>
      </infData>
    </resData>
    <extension>
      <infData xmlns="urn:X-ar:params:xml:ns:kv-1.0">
        <kvlist name="bn">
          <item key="abn">18 092 242 209</item>
          <item key="entityType">Australian Private Company</item>
        </kvlist>
      </infData>
    </extension>
    <trID>
      <clTRID>ABC-12345</clTRID>
      <svTRID>54322-XYZ</svTRID>
    </trID>
  </response>
</epp>

Servers MAY restrict all or parital arbitrary data information to authorized clients.

3.1.3.  EPP <transfer> Command

This extension does not define any extension to the EPP <transfer> command or response described in the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

3.2.  EPP Transform Commands

EPP provides five commands to transform objects: <create> to create an instance of an object, <delete> to delete an instance of an object, <renew> to extend the validity period of an object, <transfer> to manage object sponsorship changes, and <update> to change information associated with an object.

3.2.1.  EPP <create> Command

This extension defines additional elements for the EPP <create> command to be used in conjunction with the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

To enable clients to associate arbitrary data with domain objects, the <domain:create> command is extended with a <kv:create> element that contains the following child elements:

• One or more <kvlist> elements that contain the list of key-value items to be associated with the domain object, as described in Key Value Pairs (Key Value Pairs). A "name" attribute MUST be present to identify the name of the key-value list.

Example <create> command:

<?xml version="1.0" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <command>
    <create>
      <create xmlns="urn:ietf:params:xml:ns:domain-1.0">
        <name>example.tld</name>
        <period unit="y">2</period>
        <ns>
          <hostObj>ns1.example.net</hostObj>
          <hostObj>ns2.example.net</hostObj>
        </ns>
        <registrant>jd1234</registrant>
        <contact type="admin">sh8013</contact>
        <contact type="tech">sh8013</contact>
        <authInfo>
          <pw>2fooBAR</pw>
        </authInfo>
      </create>
    </create>
    <extension>
      <create xmlns="urn:X-ar:params:xml:ns:kv-1.0">
        <kvlist name="bn">
          <item key="abn">18 092 242 209</item>
          <item key="entityType">Australian Private Company</item>
        </kvlist>
      </create>
    </extension>
    <clTRID>ABC-12345</clTRID>
  </command>
</epp>

3.2.2.  EPP <delete> Command

This extension does not define any extension to the EPP <delete> command or response described in the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

3.2.3.  EPP <renew> Command

This extension does not define any extension to the EPP <renew> command or response described in the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

3.2.4.  EPP <transfer> Command

This extension does not define any extension to the EPP <transfer> command or response described in the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

3.2.5.  EPP <update> Command

This extension defines additional elements for the EPP <update> command to be used in conjunction with the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731].

To enable clients to modify the arbitrary information associated with a domain object, the <domain:update> command is extended with a <kv:create> element that contains the following child elements:

• One or more <kvlist> elements that contain the list of key-value items to be associated with the domain object, as described in Key Value Pairs (Key Value Pairs). A "name" attribute MUST be present to identify the name of the key-value list.

Updates to key-value lists SHOULD be treated as a replace operation; clients SHOULD provide the complete key-value list to remove only an optional value associated with the domain object.

Example <update> command:

<?xml version="1.0" standalone="no"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  <command>
    <update>
      <update xmlns="urn:ietf:params:xml:ns:domain-1.0">
        <name>example.com.au</name>
      </update>
    </update>
    <extension>
      <update xmlns="urn:X-ar:params:xml:ns:kv-1.0">
        <kvlist name="bn">
          <item key="abn">18 092 242 209</item>
          <item key="entityType">Australian Private Company</item>
        </kvlist>
      </update>
    </extension>
    <clTRID>ABC-12345</clTRID>
  </command>
</epp>

4.  Formal Syntax

<?xml version="1.0" standalone="no"?>
<schema targetNamespace="urn:X-ar:params:xml:ns:kv-1.0"
   xmlns="http://www.w3.org/2001/XMLSchema"
   xmlns:kv="urn:X-ar:params:xml:ns:kv-1.0"
   elementFormDefault="qualified">

   <!--
      Definition of kvlist to be reused in other DTDs
   -->
   <group name="kvlist">
      <sequence>
         <element name="kvlist" type="kv:listType" />
      </sequence>
   </group>

   <!--
      Command extension elements
    -->
   <element name="create" type="kv:createType" />
   <element name="update" type="kv:updateType" />

   <complexType name="createType">
      <group ref="kv:kvlist" maxOccurs="unbounded" />
   </complexType>

   <complexType name="updateType">
      <group ref="kv:kvlist" maxOccurs="unbounded" />
   </complexType>

   <complexType name="listType">
      <sequence maxOccurs="unbounded">
         <element name="item" type="kv:itemType" />
      </sequence>
      <attribute name="name" type="token" use="required" />
   </complexType>

   <complexType name="itemType">
      <simpleContent>
         <extension base="token">
            <attribute name="key" type="token" use="required" />
         </extension>
      </simpleContent>
   </complexType>

   <!--
      Response extension types
    -->
   <element name="infData" type="kv:infDataType" />

   <complexType name="infDataType">
      <group ref="kv:kvlist" maxOccurs="unbounded" />
   </complexType>

</schema>

5.  Security Considerations

The mapping extensions described in this document do not provide any security services beyond those described by EPP (Hollenbeck, S., “Extensible Provisioning Protocol (EPP),” August 2009.) [RFC5730], the EPP Domain Name Mapping (Hollenbeck, S., “Extensible Provisioning Protocol (EPP) Domain Name Mapping,” August 2009.) [RFC5731], and protocol layers used by EPP. The security considerations described in these other specifications apply to this specification as well.

6. Normative References

Authors' Addresses