Internet Engineering Task Force                              J. Mitchell
Internet-Draft                                                 C. Wright
Intended status: Informational                               AusRegistry
Expires: June 4, 2013                                      December 2012


    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.



















Mitchell & Wright         Expires June 4, 2013                  [Page 1]

Internet-Draft            EPP Key-Value Mapping            December 2012


Table of Contents

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






























Mitchell & Wright         Expires June 4, 2013                  [Page 2]

Internet-Draft            EPP Key-Value Mapping            December 2012


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 [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 [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



Mitchell & Wright         Expires June 4, 2013                  [Page 3]

Internet-Draft            EPP Key-Value Mapping            December 2012


   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 [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
   [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 [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:

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

   Example <info> response containing arbitrary key-value pairs




Mitchell & Wright         Expires June 4, 2013                  [Page 4]

Internet-Draft            EPP Key-Value Mapping            December 2012


   <?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



Mitchell & Wright         Expires June 4, 2013                  [Page 5]

Internet-Draft            EPP Key-Value Mapping            December 2012


   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
   [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
   [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:

   o  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 (Section 2.1).  A "name" attribute MUST be present to
      identify the name of the key-value list.





















Mitchell & Wright         Expires June 4, 2013                  [Page 6]

Internet-Draft            EPP Key-Value Mapping            December 2012


   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
   [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
   [RFC5731].







Mitchell & Wright         Expires June 4, 2013                  [Page 7]

Internet-Draft            EPP Key-Value Mapping            December 2012


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
   [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
   [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:

   o  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 (Section 2.1).  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>





Mitchell & Wright         Expires June 4, 2013                  [Page 8]

Internet-Draft            EPP Key-Value Mapping            December 2012


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



Mitchell & Wright         Expires June 4, 2013                  [Page 9]

Internet-Draft            EPP Key-Value Mapping            December 2012


       -->
      <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 [RFC5730], the EPP
   Domain Name Mapping [RFC5731], and protocol layers used by EPP.  The
   security considerations described in these other specifications apply
   to this specification as well.


6.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC5730]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              STD 69, RFC 5730, August 2009.

   [RFC5731]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Domain Name Mapping", STD 69, RFC 5731, August 2009.


Authors' Addresses

   James Mitchell
   AusRegistry
   8/10 Queens Road
   Melbourne, Victoria  3004
   AU

   Email: james.mitchell@ausregistry.com
   URI:   www.ausregistry.com









Mitchell & Wright         Expires June 4, 2013                 [Page 10]

Internet-Draft            EPP Key-Value Mapping            December 2012


   Chris Wright
   AusRegistry
   8/10 Queens Road
   Melbourne, Victoria  3004
   AU

   Email: chris@ausregistry.com
   URI:   www.ausregistry.com











































Mitchell & Wright         Expires June 4, 2013                 [Page 11]