<?xml version="1.0" encoding="US-ASCII"?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
]>

<rfc category="std" ipr="trust200902" docName="draft-blanchet-regext-entityid2rdapserver-00" submissionType="IETF" consensus="yes">

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>

<?rfc rfcedstyle="yes" ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>

<front>
<title abbrev="Finding Additional RDAP Service">Finding Additional Registration Data (RDAP) Service</title>
<author initials="M." surname="Blanchet" fullname="Marc Blanchet">
  <organization>Viagenie</organization>
  <address>
    <postal>
      <street>246 Aberdeen</street>
      <city>Quebec</city>
      <region>QC</region>
      <code>G1R 2E1</code>
      <country>Canada</country>
    </postal>
    <email>Marc.Blanchet@viagenie.ca</email>
    <uri>http://viagenie.ca</uri>
  </address>
</author>

<date month="March" year="2019" />

<keyword>whois</keyword>
<keyword>bootstrap</keyword>
<keyword>IDN</keyword>
<keyword>AS</keyword>
<keyword>IPv4</keyword>
<keyword>IPv6</keyword>
<keyword>JSON</keyword>

<abstract>
<t>This document specifies a method to find which Registration Data Access Protocol (RDAP) server is authoritative
  to answer additional information for a query already answered by another server.
  It is based on an entity id to RDAP server location mapping registry managed by IANA.
  One use case of this specification is the domain registry RDAP server providing a referral URL to the registrar RDAP server,
  based on the registrar entity id, for information that the registrar is authoritative for such as the contact
  or reseller information.
</t>
</abstract>
</front>
<middle>
  <section title="Introduction">
    <t>Finding the authoritative Registration Data Access Protocol (RDAP) server is specified in <xref target="RFC7484"/>.
     In some use cases, the authoritative server answering an RDAP query may not have all the information, but instead another server has the missing information.
     However, the first server may not know the location (URL) of that other server, but just an organization identifier, therefore it can not send a link or redirect, as
     described in <xref target="RFC7483"/>. Operationally, the location of the other server will need to be known to many servers,
     where storing the mapping centrally enables the scalable management of the locations..
   </t>
   <t>The typical use case is for domain registries where
   the RDAP server of the domain registry is not authoritative for or does not have some
   information for the query, but the registrar, a separate entity from the
   domain registry, is authoritative and does have that additional information.
   The information may include contact, reseller, expiration date information.
   The registry RDAP server needs to provide a referral location (URL) to the client,
   or provide the organization identifier for the client to map to a location (URL),
   to enable the client to retrieve the information from the registrar RDAP server.
</t>
   <t>
    This specification is generic to include other possible current or future cases,
    so it does not focus on the specific thin domain registry-registrar case
    while it uses that use case for examples.
   </t>
  </section>
<section title="Conventions Used in This Document">
<t>
   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 <xref target="RFC2119"/>.
</t>
</section>
<section title="High-Level Functional Description">
  <t>The functional description of this proposal is as follows:
  <list style="numbers">
    <t>an RDAP client finds the authoritative RDAP server using <xref target="RFC7484"/>,</t>
    <t>the client sends its query to the authoritative RDAP server,</t>
    <t>the authoritative RDAP server returns an answer as described in <xref target="RFC7483"/>
    with a reference to the identifier of an entity who has more data for this query,</t>
    <t>The client finds the RDAP server of the entity by either:
      <list style="letters">
        <t>Using a referral URL returned by the server based on the server using this specification,</t>
        <t>Using this specification to find the RDAP server of the entity, based on the entity identifier,</t>
      </list>
    </t>
    <t>the client sends the same query to the RDAP server of that entity,</t>
    <t>the server returns an answer as described in <xref target="RFC7483"/>,</t>
    <t>the client shows all the information received from both servers.</t>
  </list>
</t>
</section>
<section title="Registry of Entity to RDAP server location">
  <t>
  While it is expected that the RDAP servers will be managed by organizations, this specification uses the term "entity" to support any generic case.
  This specification defines a registry managed by IANA which maps an entity Id to its RDAP server location (URL).
  The RDAP server location information description is similar to <xref target="RFC7484"/> so that RDAP client can parse similarly for both registries.
</t>
</section>
<section title="Identifying the Entity">
<t>The organization identifier used in the RDAP answer is the key to the entry of the RDAP server registry specified in this document.
  This key should be unique in the registry. For the specific case of gTLD domain registries, ICANN through IANA has created a registry of <eref target="https://www.iana.org/assignments/registrar-ids/registrar-ids.xhtml">gTLD accredited registrars</eref>.
  In that registry, a registrar is identified by a number.
  For ccTLD domain registries, some registrars may not be in this registry, as they do not need to be accredited by ICANN.
  In a generic way not related to domain registries,
  there should be a registry of entities providing a unique number for these entities.
  IANA already have a registry of organizations identifiers, as numbers, the <eref target="https://www.iana.org/assignments/enterprise-numbers/enterprise-numbers">Private Enterprise Numbers</eref> registry,
  with a policy of first come first serve without any limitation, with <eref target="https://pen.iana.org/pen/PenApplication.page">easy registration procedure</eref>,
  used in multiple contexts for IETF protocols. This document suggests to use this registry for the assignment of unique numbers to entities.
  Therefore, this document specifies two namespaces for the entity identification: one for accredited gTLD registrars and one from the IANA private enterprise numbers registry.
  In the case of domain registries where a registrar is not in the first list, that registrar can easily get a unique organization number from the IANA organizations registry in a timely manner.
  This specification defines a registry which maps an entity id to its RDAP server location (URL). Therefore, the entity id with its namespace creates a unique key to the registry.
</t>
</section>
  <section anchor="struct" title="Structure of the Entity to RDAP Server Location Registry">
<t>The Entity to RDAP Server Location registry, as specified in <xref
target="ianaconsiderations"/> below, have been made available as JSON <xref
target="RFC7159"/> objects, which can be retrieved via HTTP from locations specified by IANA.
The JSON object for each registry contains a series of members containing metadata about the registry
such as a version identifier, a timestamp of the publication date of the registry, and a description.
Additionally, a "services" member contains the registry items themselves, as JSON objects.
Each object has a key which uniquely defines the entity and the value is an array of its RDAP server URLs.
</t>
<t>An example structure of the JSON output of the registry is illustrated:
<figure>
<artwork>
{
    "version": "1.0",
    "publication": "YYYY-MM-DDTHH:MM:SSZ",
    "description": "Some text",
    "services": {
       "entry1-accregids":
        [
          "https://registrar2.example.com/myrdap/",
          "http://registrar2.example.com/myrdap/"
        ],
       "entry2-pen":
        [
          "https://registrar4.example.com/rdap/"
        ],
        "entry3-accregids":
         [
           "https://myregistrar.example.com/rdap/"
         ]
    }
}
</artwork>
</figure>
</t>
<t>The formal syntax is described in <xref target="abnf"/>.</t>
<t>The "version" corresponds to the format version of the registry. This specification defines version "1.0".</t>
<t>The syntax of the "publication" value conforms to the Internet date/time format <xref target="RFC3339"/>. The value is the latest update date of the registry by IANA.</t>
<t>The optional "description" string can contain a comment regarding the content of the registry. </t>
<t>Per <xref target="RFC7258"/>, in each array of base RDAP URLs, the secure versions of the transport protocol SHOULD be preferred and tried first.
For example, if the base RDAP URLs array contains both HTTPS and HTTP URLs, the client SHOULD try the HTTPS version first.</t>
<t>Base RDAP URLs MUST have a trailing "/" character because they are concatenated to the various segments defined in <xref target="RFC7482"/>.</t>
<t>JSON names MUST follow the format recommendations of <xref target="RFC7480"/>. Any unrecognized JSON object properties or values MUST be
 ignored by implementations.</t>
 <t>The syntax of the keys is as follows:
   <list style="symbols">
     <t>entity: a unsigned integer encoded in ASCII</t>
     <t>separator: the 0x2d ASCII hyphen</t>
     <t>namespace: either "accregids" for an entity id from the IANA accredited registrar Ids registry
       or "pen" for an entity id from the IANA Private Enterprise Numbers registry</t>
   </list>
</t>
</section>
<section anchor="abnf" title="Formal Definition">
<t>This section is the formal definition of the registries. The structure of JSON objects and arrays using a set of primitive elements
  is defined in <xref target="RFC7159"/>. Those elements are used to describe the JSON structure of the registries.</t>

<section title="Imported JSON Terms">

<t>
<list style="symbols">
  <t>OBJECT: a JSON object, defined in Section 4 of <xref target="RFC7159"/></t>
  <t>MEMBER: a member of a JSON object, defined in Section 4 of <xref target="RFC7159"/></t>
  <t>MEMBER-NAME: the name of a MEMBER, defined as a "string" in
      Section 4 of <xref target="RFC7159"/></t>
  <t>MEMBER-VALUE: the value of a MEMBER, defined as a "value" in
      Section 4 of <xref target="RFC7159"/></t>
  <t>ARRAY:  an array, defined in Section 5 of <xref target="RFC7159"/></t>
  <t>ARRAY-VALUE: an element of an ARRAY, defined in Section 5 of
      <xref target="RFC7159"/></t>
  <t>STRING: a "string", as defined in Section 7 of <xref target="RFC7159"/></t>
 </list>
</t>
 </section>
 <section title="Registry Syntax">
<t>Using the above terms for the JSON structures, the syntax of a
   registry is defined as follows:
   TBD
<list style="symbols">
 <t>rdap-entity2server-registry: an OBJECT containing a MEMBER version and
    a MEMBER publication, an optional MEMBER description, and a MEMBER services-list</t>
 <t>version: a MEMBER with MEMBER-NAME "version" and
      MEMBER-VALUE a STRING</t>
 <t>publication: a MEMBER with MEMBER-NAME "publication" and
      MEMBER-VALUE a STRING</t>
 <t>description: a MEMBER with MEMBER-NAME "description" and
      MEMBER-VALUE a STRING</t>
 <t>services-list: a MEMBER with MEMBER-NAME "services" and </t>
 <t>TDB</t>
 <t>service-uri-list: an ARRAY, where each ARRAY-VALUE is a service-uri</t>
 <t>service-uri: a STRING</t>
   </list>
  </t>
  </section>
</section>
<section title="Recursive Referrals">
  <t>This specification does not restrict the use of recursive links. For example, the answer from the additional RDAP server may itself contain reference to other servers, hence the possibility of recursion.
    However, without limits, this may end up with infinite recursion. Based on its use case, the RDAP client should set a limit on the number of referrals it will follow.
    In the specific case of thin domain registries with registrars RDAP servers, there should be a limit of 2 levels: the domain registry RDAP server and the registrar RDAP server.
  </t>
</section>
<section title="Merging the Data Received from Multiple RDAP Servers">
  <t>The answer from the additional RDAP server may contain data that overlaps with the answer from the initial authoritative RDAP server.
    This document does not specify which data should be chosen in case of overlaps or conflicts, since it depends on the use case.
    In the specific case of thin domain registries with registrars RDAP servers,
    the data received by all RDAP servers should be additive and shown appropriately to the user. For example, if the domain registry RDAP server answer contains an expiration date
     for the domain queried, and if the registrar RDAP server answer also contains an expiration date,
     then the two expiration dates are shown to the user of the RDAP client.
</t>
</section>
<section title="Security Considerations">
   <t>By providing a method to find an entity RDAP servers, this document
   helps to ensure that the end users will get the RDAP data from an
   authoritative source, instead of from rogue sources. The method has the
   same security properties as the RDAP protocols themselves.

 The transport used to access the registries can be more secure by using
 TLS <xref target="RFC5246"/>, which IANA supports.
   </t>

<t>Additional considerations on using RDAP are described in <xref target="RFC7481"/>.</t>
</section>
<section anchor="ianaconsiderations" title="IANA Considerations">
<t>IANA has created the RDAP Entity to RDAP Server Location Registry, listed below,
and made them available as JSON objects.  The contents of these registries are described in <xref target="struct"/> with the formal syntax specified in <xref target="abnf"/>.</t>

<t>Because this registry will be accessed by software, the download demand may be unusually high compared to
normal IANA registries.  The technical infrastructure by which registries are
published will need to be reviewed and might need to be augmented.</t>

<t>Software accessing these registries will depend on the HTTP Expires header field to limit their query rate.
It is, therefore, important for that header field to be properly set to provide timely information as the registries change,
while maintaining a reasonable load on the IANA servers.</t>

<t>The HTTP Content-Type returned to clients accessing these JSON-formatted registries MUST be "application/json", as defined in <xref target="RFC7159"/>.</t>

<t>The registry entries may not be sorted.</t>

</section>
<section title="Discussion of this draft">
  <t>this is a todo list for the author on topics to be done/resolved, or comments received.
    This section will disappear when draft is finished.
  <list style="symbols">
    <t>should this document merge with RFC7484 and become "RFC7484-bis"</t>
    <t>identify the exact field the first server refers to the entity</t>
    <t>Additional namespaces may be added with updates of this specification. we don't want to setup a registry of namespace, do we?</t>
    <t>The process for adding or updating entries in these registries should be defined here</t>
  </list>
</t>
<t>alternate structure proposed by James Gould:
<figure>
<artwork>
  {
  "description": "RDAP bootstrap file for registry to registrar referrals",
  "publication": "2019-02-14T02:00:02Z",
  "repositories": [
    {
      "id": "ICANN",
      "description": "ICANN registrar repository for ICANN accredited registrars",
      "registrars": [
        {
          "id": "292",
          "description": "MarkMonitor",
          "url": "https://rdap.markmonitor.com/rdap/"
        }
      ]
    },
    {
      "id": "US",
      "description": "US registry repository for US registrars",
      "registrars": [
        {
          "id": "9999",
          "description": "Example non-ICANN accredited registrar for .US ccTLD",
          "url": "https://rdap.registrar.example/rdap/"
        }
      ]
    }
  ]
}
</artwork>
</figure>
</t>
</section>

</middle>
<back>
  <references title="Normative References">
    <?rfc include="reference.RFC.2119"?>
    <?rfc include="reference.RFC.3339"?>
    <?rfc include="reference.RFC.7159"?>
  </references>

  <references title="Informative References">

    <?rfc include="reference.RFC.5246"?>
    <?rfc include="reference.RFC.7258"?>
    <?rfc include="reference.RFC.7480"?>
    <?rfc include="reference.RFC.7481"?>
    <?rfc include="reference.RFC.7482"?>
    <?rfc include="reference.RFC.7483"?>
    <?rfc include="reference.RFC.7484"?>
 </references>
 <section title="Acknowledgements" numbered="no">
     <t>The following people have provided comments and reviews improving the document significantly (in no particular order):
       Audric Schiltknecht, Julien Bernard, James Gould.</t>
</section>
</back>
</rfc>
