Registration Protocols Extensions (regext)                      G. Brown
Internet-Draft                                      CentralNic Group plc
Intended status: Standards Track                           27 March 2023
Expires: 28 September 2023


  Extensible Provisioning Protocol (EPP) Extension for Related Objects
               draft-regext-brown-epp-related-objects-00

Abstract

   This document describes an extension to the Extensible Provisioning
   Protocol (EPP) that allows EPP clients to request the inclusion of
   related objects in responses to <info> commands.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   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 https://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 28 September 2023.

Copyright Notice

   Copyright (c) 2023 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.






Brown                   Expires 28 September 2023               [Page 1]

Internet-Draft      Related Objects Extension for EPP         March 2023


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
     1.1.  Conventions used in this document . . . . . . . . . . . .   2
   2.  EPP <info> command  . . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Response  . . . . . . . . . . . . . . . . . . . . . . . .   4
   3.  Inclusion of related objects in <info> responses  . . . . . .   6
   4.  Security considerations . . . . . . . . . . . . . . . . . . .   7
   5.  IANA considerations . . . . . . . . . . . . . . . . . . . . .   7
     5.1.  XML namespace . . . . . . . . . . . . . . . . . . . . . .   7
     5.2.  EPP extension registry  . . . . . . . . . . . . . . . . .   7
   6.  Formal specification  . . . . . . . . . . . . . . . . . . . .   8
   7.  Normative references  . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  10

1.  Introduction

   The Extensible Provisioning Protocol (EPP) [RFC5730] is an object
   provisioning and management protocol, allowing clients to create,
   view and transform objects in a central repository.

   The EPP <info> command allows clients to retrieve information
   (subject to authorisation) about objects in the repository.  Since
   EPP operates on a strictly per-object basis, and since objects may be
   related to one another, a client may often need to issue multiple
   <info> commands in order to retrieve the data it needs to carry out
   its operation.

   This document describes an extension to the <info> command that
   allows clients to request the inclusion of information about related
   objects in responses.  This allows clients to retrieve all the
   required information about an object in a single round-trip to the
   server.

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

   In examples, C: represents lines sent by a protocol client and S:
   represents lines returned by a protocol server.  Indentation and
   white space in examples are provided only to illustrate element
   relationships and are not REQUIRED features of this protocol.

   A protocol client that is authorized to manage an existing object is
   described as a "sponsoring" client throughout this document.




Brown                   Expires 28 September 2023               [Page 2]

Internet-Draft      Related Objects Extension for EPP         March 2023


   XML is case sensitive.  Unless stated otherwise, XML specifications
   and examples provided in this document MUST be interpreted in the
   character case presented in order to develop a conforming
   implementation.

   EPP uses XML namespaces to provide an extensible object management
   framework and to identify schemas required for XML instance parsing
   and validation.  These namespaces and schema definitions are used to
   identify both the base protocol schema and the schemas for managed
   objects.

   The XML namespace prefixes used in examples (such as the string ro in
   ro:include) are solely for illustrative purposes.  A conforming
   implementation MUST NOT require the use of these or any other
   specific namespace prefixes.

2.  EPP <info> command

   This extension defines additional elements to extend the EPP <info>
   command and response.

   Clients wishing to request related object information MUST include a
   <ro:info> element in the <extension> element of the <info> frame.
   The <ro:info> element contains a <ro:include> element which MUST
   contain one or more of the following child elements:

   *  <ro:registrant/>, which requests the inclusion of the contact
      object [RFC5733] corresponding to a domain's registrant;

   *  <ro:contacts/>, which requests the inclusion of the
      administrative, technical and billing contacts for a domain;

   *  <ro:orgs/>, which requests the inclusion of the organisations
      [RFC8544] associated with a domain;

   *  <ro:ns/>, which requests the inclusion of the host object(s)
      [RFC5732] to which a domain is delegated;

   *  <ro:hosts/>, which requests the inclusion of any subordinate host
      objects of a domain (see Section 1.1 of [RFC5731]);

   *  <ro:other/>, which requests the inclusion of other related objects
      not covered by the previous elements, such as those described in
      future EPP extensions.

   Example <info> command:





Brown                   Expires 28 September 2023               [Page 3]

Internet-Draft      Related Objects Extension for EPP         March 2023


  C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
  C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
  C:  <command>
  C:    <info>
  C:      <domain:info xmlns:domain="urn:ietf:params:xml:ns:domain-1.0">
  C:        <domain:name hosts="all">example.com</domain:name>
  C:      </domain:info>
  C:    </info>
  C:    <extension>
  C:      <ro:info
  C:        xmlns:ro="urn:ietf:params:xml:ns:epp:relatedObjects-1.0">
  C:        <ro:include>
  C:          <ro:registrant/>
  C:          <ro:ns/>
  C:          <ro:other/>
  C:        </ro:include>
  C:      </ro:info>
  C:    </extension>
  C:    <clTRID>ABC-12345</clTRID>
  C:  </command>
  C:</epp>

2.1.  Response

   A server responding to an <info> command that has been extended with
   a <ro:info> element MAY include an <ro:infData> element in the
   <extension> element of the response.

   If present, the <ro:infData> element MUST include one or more
   <infData> elements, scoped to the namespace URI of an EPP object
   mapping.

   Example <info> response:

   S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
   S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
   S:  <response>
   S:    <result code="1000">
   S:      <msg>Command completed successfully</msg>
   S:    </result>
   S:    <resData>
   S:      <domain:infData
   S:        xmlns:domain="urn:ietf:params:xml:ns:domain-1.0">
   S:        <domain:name>example.com</domain:name>
   S:        <domain:roid>EXAMPLE1-REP</domain:roid>
   S:        <domain:status s="ok"/>
   S:        <domain:registrant>jd1234</domain:registrant>
   S:        <domain:contact type="admin">sh8013</domain:contact>



Brown                   Expires 28 September 2023               [Page 4]

Internet-Draft      Related Objects Extension for EPP         March 2023


   S:        <domain:contact type="tech">sh8013</domain:contact>
   S:        <domain:ns>
   S:          <domain:hostObj>ns1.example.com</domain:hostObj>
   S:          <domain:hostObj>ns1.example.net</domain:hostObj>
   S:        </domain:ns>
   S:        <domain:host>ns1.example.com</domain:host>
   S:        <domain:host>ns2.example.com</domain:host>
   S:        <domain:clID>ClientX</domain:clID>
   S:        <domain:crID>ClientY</domain:crID>
   S:        <domain:crDate>1999-04-03T22:00:00.0Z</domain:crDate>
   S:        <domain:upID>ClientX</domain:upID>
   S:        <domain:upDate>1999-12-03T09:00:00.0Z</domain:upDate>
   S:        <domain:exDate>2005-04-03T22:00:00.0Z</domain:exDate>
   S:        <domain:trDate>2000-04-08T09:00:00.0Z</domain:trDate>
   S:        <domain:authInfo>
   S:          <domain:pw>2fooBAR</domain:pw>
   S:        </domain:authInfo>
   S:      </domain:infData>
   S:    </resData>
   S:    <extension>
   S:      <ro:infData
   S:        xmlns:ro="urn:ietf:params:xml:ns:epp:relatedObjects-1.0">
   S:        <contact:infData
   S:          xmlns:contact="urn:ietf:params:xml:ns:contact-1.0">
   S:          <contact:id>jd1234</contact:id>
   S:          <contact:roid>JD1234-REP</contact:roid>
   S:          <contact:status s="linked"/>
   S:          <contact:status s="clientDeleteProhibited"/>
   S:          <contact:postalInfo type="int">
   S:            <contact:name>John Doe</contact:name>
   S:            <contact:org>Example Inc.</contact:org>
   S:            <contact:addr>
   S:              <contact:street>123 Example Dr.</contact:street>
   S:              <contact:street>Suite 100</contact:street>
   S:              <contact:city>Dulles</contact:city>
   S:              <contact:sp>VA</contact:sp>
   S:              <contact:pc>20166-6503</contact:pc>
   S:              <contact:cc>US</contact:cc>
   S:            </contact:addr>
   S:          </contact:postalInfo>
   S:          <contact:voice x="1234">+1.7035555555</contact:voice>
   S:          <contact:email>jdoe@example.com</contact:email>
   S:          <contact:clID>ClientY</contact:clID>
   S:          <contact:crID>ClientX</contact:crID>
   S:          <contact:crDate>1999-04-03T22:00:00.0Z</contact:crDate>
   S:        </contact:infData>
   S:        <host:infData
   S:          xmlns:host="urn:ietf:params:xml:ns:host-1.0">



Brown                   Expires 28 September 2023               [Page 5]

Internet-Draft      Related Objects Extension for EPP         March 2023


   S:          <host:name>ns1.example.com</host:name>
   S:          <host:roid>NS1_EXAMPLE1-REP</host:roid>
   S:          <host:status s="linked"/>
   S:          <host:addr ip="v4">192.0.2.2</host:addr>
   S:          <host:clID>ClientY</host:clID>
   S:          <host:crID>ClientX</host:crID>
   S:          <host:crDate>1999-04-03T22:00:00.0Z</host:crDate>
   S:        </host:infData>
   S:        <host:infData
   S:          xmlns:host="urn:ietf:params:xml:ns:host-1.0">
   S:          <host:name>ns1.example.net</host:name>
   S:          <host:roid>NS1_EXAMPLE2-REP</host:roid>
   S:          <host:status s="linked"/>
   S:          <host:addr ip="v4">192.0.2.29</host:addr>
   S:          <host:clID>ClientY</host:clID>
   S:          <host:crID>ClientX</host:crID>
   S:          <host:crDate>1999-04-03T22:00:00.0Z</host:crDate>
   S:        </host:infData>
   S:      </ro:infData>
   S:    </extension>
   S:    <trID>
   S:      <clTRID>ABC-12345</clTRID>
   S:      <svTRID>54322-XYZ</svTRID>
   S:    </trID>
   S:  </response>
   S:</epp>

3.  Inclusion of related objects in <info> responses

   Servers MAY choose to include all, some, or none of the relevant
   requested objects in the <ro:infData> element, according to
   applicable policies.

   When determining whether to include a related object in the
   <ro:infData> element, servers SHOULD apply the same access control
   rules that are used to determine whether a client is authorised to
   perform an <info> on those objects.

   Since EPP does not provide a way for servers to indicate a partial
   success or failure of a command, servers MUST NOT return an error if
   a related object cannot be included in a response.  Instead, the
   object should simply be omitted from the <ro:infData> element.  An
   error response MUST only be used when the server cannot disclose the
   information about the "primary" object, that is, the object specified
   in the <info> element.






Brown                   Expires 28 September 2023               [Page 6]

Internet-Draft      Related Objects Extension for EPP         March 2023


4.  Security considerations

   The extension described in this document does not provide any
   security services or introduce any additional considerations beyond
   those described by [RFC5730] or those caused by the protocol layers
   used by EPP.

5.  IANA considerations

5.1.  XML namespace

   This document uses URNs to describe XML namespaces and XML schemas
   conforming to a registry mechanism described in [RFC3688].  The
   following URI assignment has been made by IANA:

   Registration for the TTL namespace:

      *URI:* urn:ietf:params:xml:ns:epp:relatedObjects-1.0

      *Registrant Contact:* See the author of this document

      *XML:* None.  Namespace URIs do not represent an XML specification

   Registration for the TTL XML schema:

      *URI:* urn:ietf:params:xml:ns:epp:relatedObjects-1.0

      *Registrant Contact:* See the author of this document

      *XML:* See the "Formal specification" section of this document

5.2.  EPP extension registry

   The EPP extension described in this document has been registered by
   the IANA in the Extensions for the "Extensible Provisioning Protocol
   (EPP)" registry described in [RFC7451].  The details of the
   registration are as follows:

      *Name of Extension:* Extensible Provisioning Protocol (EPP)
      Extension for Related Objects

      *Document Status:* Standards Track

      *Reference:* URL of this document

      *Registrant Name and Email Address:* See the author of this
      document




Brown                   Expires 28 September 2023               [Page 7]

Internet-Draft      Related Objects Extension for EPP         March 2023


      *TLDs:* Any

      *IPR Disclosure:* None

      *Status:* Active

      *Notes:* None

6.  Formal specification










































Brown                   Expires 28 September 2023               [Page 8]

Internet-Draft      Related Objects Extension for EPP         March 2023


   <?xml version="1.0" encoding="UTF-8"?>
   <schema
     targetNamespace="urn:ietf:params:xml:ns:epp:relatedObjects-1.0"
     xmlns:ro="urn:ietf:params:xml:ns:epp:relatedObjects-1.0"
     xmlns="http://www.w3.org/2001/XMLSchema"
     elementFormDefault="qualified">
     <annotation>
       <documentation>
         Extensible Provisioning Protocol v1.0 extension schema for
         related objects.
       </documentation>
     </annotation>

     <element name="info"  type="ro:info" />
     <element name="infData" type="ro:infData" />

     <complexType name="info">
       <sequence>
         <element name="include" type="ro:include" />
       </sequence>
     </complexType>

     <complexType name="include">
       <all>
         <element name="registrant" minOccurs="0" maxOccurs="1" />
         <element name="contacts" minOccurs="0" maxOccurs="1" />
         <element name="orgs" minOccurs="0" maxOccurs="1" />
         <element name="ns" minOccurs="0" maxOccurs="1" />
         <element name="hosts" minOccurs="0" maxOccurs="1" />
         <element name="other" minOccurs="0" maxOccurs="1" />
       </all>
     </complexType>

     <complexType name="infData">
       <sequence>
         <element name="infData" namespace="##other"
           minOccurs="1" maxOccurs="unbounded" />
       </sequence>
     </complexType>
   </schema>

7.  Normative references

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.




Brown                   Expires 28 September 2023               [Page 9]

Internet-Draft      Related Objects Extension for EPP         March 2023


   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              DOI 10.17487/RFC3688, January 2004,
              <https://www.rfc-editor.org/info/rfc3688>.

   [RFC5730]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
              STD 69, RFC 5730, DOI 10.17487/RFC5730, August 2009,
              <https://www.rfc-editor.org/info/rfc5730>.

   [RFC5731]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Domain Name Mapping", STD 69, RFC 5731,
              DOI 10.17487/RFC5731, August 2009,
              <https://www.rfc-editor.org/info/rfc5731>.

   [RFC5732]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Host Mapping", STD 69, RFC 5732, DOI 10.17487/RFC5732,
              August 2009, <https://www.rfc-editor.org/info/rfc5732>.

   [RFC5733]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
              Contact Mapping", STD 69, RFC 5733, DOI 10.17487/RFC5733,
              August 2009, <https://www.rfc-editor.org/info/rfc5733>.

   [RFC7451]  Hollenbeck, S., "Extension Registry for the Extensible
              Provisioning Protocol", RFC 7451, DOI 10.17487/RFC7451,
              February 2015, <https://www.rfc-editor.org/info/rfc7451>.

   [RFC8544]  Zhou, L., Kong, N., Wei, J., Yao, J., and J. Gould,
              "Organization Extension for the Extensible Provisioning
              Protocol (EPP)", RFC 8544, DOI 10.17487/RFC8544, April
              2019, <https://www.rfc-editor.org/info/rfc8544>.

Author's Address

   Gavin Brown
   CentralNic Group plc
   44 Gutter Lane
   London
   EC2V 6BR
   United Kingdom
   Phone: +44 20 33 88 0600
   Email: gavin.brown@centralnic.com
   URI:   https://www.centralnic.com










Brown                   Expires 28 September 2023              [Page 10]