RFC 4932

Extensible Provisioning Protocol (EPP) Host Mapping

📅 published May 2007, from ietf

Extensible Provisioning Protocol (EPP) Host Mapping 💅

Okay bestie, this is RFC 4932 🎀. It's from the Network Working Group, written by S. Hollenbeck at VeriSign, Inc., and dated May 2007 🌸. It's a Standards Track doc, so it's an actual Internet standards protocol spec 👑. It obsoletes RFC 3732, so that one is retired now 💀.

Status of This Memo ✨

This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited.

Copyright (C) The IETF Trust (2007).

Abstract 🌈

This document describes an Extensible Provisioning Protocol (EPP) mapping for the provisioning and management of Internet host names stored in a shared central repository. Specified in XML, the mapping defines EPP command syntax and semantics as applied to host names. This document obsoletes RFC 3732.

Table of Contents 📚

1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
  1.1.  Relationship of Host Objects and Domain Objects  . . . . .  3
  1.2.  Conventions Used in This Document  . . . . . . . . . . . .  4
2.  Object Attributes  . . . . . . . . . . . . . . . . . . . . . .  4
  2.1.  Host Names . . . . . . . . . . . . . . . . . . . . . . . .  4
  2.2.  Client Identifiers . . . . . . . . . . . . . . . . . . . .  4
  2.3.  Status Values  . . . . . . . . . . . . . . . . . . . . . .  4
  2.4.  Dates and Times  . . . . . . . . . . . . . . . . . . . . .  6
  2.5.  IP Addresses . . . . . . . . . . . . . . . . . . . . . . .  6
3.  EPP Command Mapping  . . . . . . . . . . . . . . . . . . . . .  7
  3.1.  EPP Query Commands . . . . . . . . . . . . . . . . . . . .  7
    3.1.1.  EPP <check> Command  . . . . . . . . . . . . . . . . .  7
    3.1.2.  EPP <info> Command . . . . . . . . . . . . . . . . . .  9
    3.1.3.  EPP <transfer> Query Command . . . . . . . . . . . . . 11
  3.2.  EPP Transform Commands . . . . . . . . . . . . . . . . . . 11
    3.2.1.  EPP <create> Command . . . . . . . . . . . . . . . . . 12
    3.2.2.  EPP <delete> Command . . . . . . . . . . . . . . . . . 13
    3.2.3.  EPP <renew> Command  . . . . . . . . . . . . . . . . . 15
    3.2.4.  EPP <transfer> Command . . . . . . . . . . . . . . . . 15
    3.2.5.  EPP <update> Command . . . . . . . . . . . . . . . . . 15
  3.3.  Offline Review of Requested Actions  . . . . . . . . . . . 17
4.  Formal Syntax  . . . . . . . . . . . . . . . . . . . . . . . . 19
5.  Internationalization Considerations  . . . . . . . . . . . . . 24
6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 25
7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 25
8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 26
9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  9.1.  Normative References . . . . . . . . . . . . . . . . . . . 26
  9.2.  Informative References . . . . . . . . . . . . . . . . . . 27
Appendix A.  Changes from RFC 3732 . . . . . . . . . . . . . . . . 28

1. Introduction ✨

Okay so this doc is the Internet host name mapping for version 1.0 of EPP 💖. The mapping is written in XML 1.0, as described in [W3C.REC-xml-20040204], and it uses XML Schema notation as described in [W3C.REC-xmlschema-1-20041028] and [W3C.REC-xmlschema-2-20041028]. It obsoletes RFC 3732 [RFC3732].

[RFC4930] is the full guide to EPP command and response structures 🧚. You really need to get the base protocol spec down before this mapping makes sense.

XML is case sensitive, bestie 🙈 Unless it says otherwise, the XML specifications and examples in this document MUST be interpreted in the character case they're shown in, if you're building a conforming implementation.

1.1. Relationship of Host Objects and Domain Objects 🦋

Host name objects have a subordinate relationship to a superordinate domain name object. For example, host name ns1.example.com has a subordinate relationship to domain name example.com. EPP actions (such as object transfers) that do not preserve this relationship MUST be explicitly disallowed.

A host name object can be created in a repository where no superordinate domain name object exists. For example, host name ns1.example.com can be created in the .example repository so that DNS domains in .example can be delegated to the host. These hosts are called "external" hosts in this specification, since the name of the host doesn't belong to the name space of the repository where the host is being used for delegation.

Whether a host is external or internal depends on the repository where the host is being used for delegation. Whether or not an internal host is subordinate depends on a domain within the repository. For example, host ns1.example1.com is a subordinate host of domain example1.com, but it is not a subordinate host of domain example2.com. ns1.example1.com can be used as a name server for example2.com. In this case, ns1.example1.com MUST be treated as an internal host, subject to the rules governing operations on subordinate hosts within the same repository.

1.2. 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 only there to show how elements relate, and they are not a REQUIRED feature of this protocol 💅.

2. Object Attributes 🎀

An EPP host object has attributes and associated values that can be viewed and modified by the sponsoring client or the server. This section describes each attribute type in detail. The formal syntax for the attribute values described here can be found in the "Formal Syntax" section of this document and in the appropriate normative references.

2.1. Host Names 🌈

The syntax for host names described in this document MUST conform to [RFC0952] as updated by [RFC1123]. At the time of this writing, RFC 3490 [RFC3490] describes a standard for using certain ASCII name labels to represent non-ASCII name labels. These conformance requirements might change in the future as a result of ongoing work on standards for internationalized host names 🦄.

2.2. Client Identifiers 🍓

All EPP clients are identified by a server-unique identifier. Client identifiers conform to the "clIDType" syntax described in [RFC4930].

2.3. Status Values 💜

A host object MUST always have at least one associated status value. Status values MAY be set only by the client that sponsors a host object and by the server where the object lives. A client can change the status of a host object using the EPP <update> command. Each status value MAY be accompanied by a string of human-readable text that describes the rationale for the status applied to the object.

A client MUST NOT alter status values set by the server. A server MAY alter or override status values set by a client, subject to local server policies. The status of an object MAY change as a result of either a client-initiated transform command or an action performed by a server operator.

Status values that a client can add or remove are prefixed with client. The matching status values that a server can add or remove are prefixed with server. Status values that don't begin with either client or server are server-managed 🧁.

Status Value Descriptions:

  • clientDeleteProhibited, serverDeleteProhibited
    • Requests to delete the object MUST be rejected.
  • clientUpdateProhibited, serverUpdateProhibited
    • Requests to update the object (other than to remove this status) MUST be rejected.
  • linked
    • The host object has at least one active association with another object, such as a domain object. Servers SHOULD provide services to determine existing object associations.
  • ok
    • This is the normal status value for an object that has no pending operations or prohibitions. This value is set and removed by the server as other status values are added or removed.
  • pendingCreate, pendingDelete, pendingTransfer, pendingUpdate
    • A transform command has been processed for the object (or, in the case of a <transfer> command, for the host object's superordinate domain object), but the action has not been completed by the server. Server operators can delay action completion for a variety of reasons, such as to allow for human review or third-party action. A transform command that is processed, but whose requested action is pending, is noted with response code 1001. ⏳

When the requested action has been completed, the pendingCreate, pendingDelete, pendingTransfer, or pendingUpdate status value MUST be removed. All clients involved in the transaction MUST be notified, using a service message, that the action has been completed and that the status of the object has changed 📨.

ok status MAY only be combined with linked status.

linked status MAY be combined with any status.

pendingDelete status MUST NOT be combined with either clientDeleteProhibited or serverDeleteProhibited status.

pendingUpdate status MUST NOT be combined with either clientUpdateProhibited or serverUpdateProhibited status.

The pendingCreate, pendingDelete, pendingTransfer, and pendingUpdate status values MUST NOT be combined with each other.

Other status combinations that aren't expressly prohibited MAY be used 🔥.

2.4. Dates and Times ⭐

Date and time attribute values MUST be represented in Universal Coordinated Time (UTC) using the Gregorian calendar. The extended date-time form, using upper case "T" and "Z" characters as defined in [W3C.REC-xmlschema-2-20041028], MUST be used to represent date-time values, because XML Schema doesn't support truncated date-time forms or lower case "T" and "Z" characters 🕰️.

2.5. IP Addresses 🌷

The syntax for IPv4 addresses described in this document MUST conform to [RFC0791]. The syntax for IPv6 addresses described in this document MUST conform to [RFC4291]. Practical considerations for publishing IPv6 address information in zone files are documented in [RFC1886], [RFC2874], and [RFC3152]. A server MAY reject IP addresses that have not been allocated for public use by IANA. When a host object is provisioned for use as a DNS name server, IP addresses SHOULD be required only as needed to generate DNS glue records 🌐.

3. EPP Command Mapping 🧚

A detailed description of the EPP syntax and semantics can be found in [RFC4930]. The command mappings described here are specifically for provisioning and managing Internet host names via EPP, so this is where the real fun starts 🦋.

3.1. EPP Query Commands 🔍

EPP provides two commands to retrieve host information: <check> to determine if a host object can be provisioned within a repository, and <info> to retrieve detailed information associated with a host object 💖.

3.1.1. EPP <check> Command

okay so the EPP <check> command is how a client asks "hey, can I even make this object?" 🔍 It's basically a sneak peek so you can guess whether a <create> will go through, bc ngl, whether something can be provisioned is ultimately up to server policy 🫶

the <check> command MUST contain a <host:check> element that names the host namespace 🎀 inside that, you get one or more <host:name> elements with the fully qualified names of the host objects you wanna query 💅

Example <check> command:

C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C:  <command>
C:    <check>
C:      <host:check
C:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
C:        <host:name>ns1.example.com</host:name>
C:        <host:name>ns2.example.com</host:name>
C:        <host:name>ns3.example.com</host:name>
C:      </host:check>
C:    </check>
C:    <clTRID>ABC-12345</clTRID>
C:  </command>
C:</epp>

when a <check> command gets processed successfully, the EPP <resData> element MUST contain a <host:chkData> child element with the host namespace 🦋 that one has one or more <host:cd> elements, and each of those holds:

  • a <host:name> element with the fully qualified name of the host object that got queried. this one MUST have an "avail" attribute that tells you if the object is available (can it be provisioned or not) at the moment the <check> finished ✨ "1" or "true" means yes it can be provisioned, and "0" or "false" means nope, it can't 🙅‍♀️
  • an OPTIONAL <host:reason> element that MAY show up when an object can't be provisioned 🥺 if it's there, it has server-specific text explaining why. that text MUST be in the response language you negotiated with the client earlier 🌍 and an OPTIONAL "lang" attribute MAY be included to name the language, but only if it's something other than the default "en" (English) 🇬🇧

Example <check> 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:      <host:chkData
S:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
S:        <host:cd>
S:          <host:name avail="1">ns1.example.com</host:name>
S:        </host:cd>
S:        <host:cd>
S:          <host:name avail="0">ns2.example2.com</host:name>
S:          <host:reason>In use</host:reason>
S:        </host:cd>
S:        <host:cd>
S:          <host:name avail="1">ns3.example3.com</host:name>
S:        </host:cd>
S:      </host:chkData>
S:    </resData>
S:    <trID>
S:      <clTRID>ABC-12345</clTRID>
S:      <svTRID>54322-XYZ</svTRID>
S:    </trID>
S:  </response>
S:</epp>
an EPP error response MUST be returned if a <check> command can't be processed for any reason 😭 no silent failures, bestie!

3.1.2. EPP <info> Command

the EPP <info> command is how you pull up the info on a host object 🧚 in addition to the standard EPP command elements, the <info> command MUST contain a <host:info> element naming the host namespace. inside it goes a <host:name> element with the fully qualified name of the host object you're asking about 💜

Example <info> command:

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:      <host:info
C:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
C:        <host:name>ns1.example.com</host:name>
C:      </host:info>
C:    </info>
C:    <clTRID>ABC-12345</clTRID>
C:  </command>
C:</epp>

when an <info> command gets processed successfully, the EPP <resData> element MUST contain a <host:infData> child element that names the host namespace 🌸 the <host:infData> element holds these child elements:

  • a <host:name> element with the fully qualified name of the host object 🍓
  • a <host:roid> element with the Repository Object IDentifier that got assigned to the host object when it was created 🪪
  • one or more <host:status> elements that describe the status of the host object 🚦
  • zero or more <host:addr> elements with the IP addresses associated with the host object 🌐
  • a <host:clID> element with the identifier of the sponsoring client 👑
  • a <host:crID> element with the identifier of the client that created the host object 🛠️
  • a <host:crDate> element with the date and time the host object was created 📅
  • a <host:upID> element with the identifier of the client that last updated the host object 🙋‍♀️ this one MUST NOT be present if the host object has never been modified 🙅‍♀️
  • a <host:upDate> element with the date and time of the most recent host object modification 🕰️ this one MUST NOT be present if the host object has never been modified either 🙈
  • a <host:trDate> element with the date and time of the most recent successful host object transfer 🦋 this one MUST NOT be provided if the host object has never been transferred. also, host objects MUST NOT be transferred directly 🫢 they MUST be transferred implicitly when their superordinate domain object is transferred. the host objects that get transferred along with a domain object are listed in the response to an EPP <info> command run on that domain object 📋

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:      <host:infData
S:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
S:        <host:name>ns1.example.com</host:name>
S:        <host:roid>NS1_EXAMPLE1-REP</host:roid>
S:        <host:status s="linked"/>
S:        <host:status s="clientUpdateProhibited"/>
S:        <host:addr ip="v4">192.0.2.2</host:addr>
S:        <host:addr ip="v4">192.0.2.29</host:addr>
S:        <host:addr ip="v6">1080:0:0:0:8:800:200C:417A</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:upID>ClientX</host:upID>
S:        <host:upDate>1999-12-03T09:00:00.0Z</host:upDate>
S:        <host:trDate>2000-04-08T09:00:00.0Z</host:trDate>
S:      </host:infData>
S:    </resData>
S:    <trID>
S:      <clTRID>ABC-12345</clTRID>
S:      <svTRID>54322-XYZ</svTRID>
S:    </trID>
S:  </response>
S:</epp>
an EPP error response MUST be returned if an <info> command can't be processed for any reason 💀 same energy as <check>, no exceptions!

3.1.3. EPP <transfer> Query Command

transfer semantics don't directly apply to host objects 🙃 so there's no mapping defined for the EPP <transfer> query command. it's just not a thing for hosts, periodt 💅

3.2. EPP Transform Commands

EPP gives you three commands to transform host objects ✨ <create> makes an instance of a host object, <delete> deletes one, and <update> changes the info attached to a host object 🛠️ this document doesn't define host object mappings for the EPP <renew> and <transfer> commands, so those are a no-go here 🚫

transform commands usually get processed and completed in real time ⚡ server operators MAY receive and process transform commands, but they can defer completing the requested action if human or third-party review is needed first 🧐 in that situation, the server MUST return a 1001 response code to let the client know the command was received and processed, but the requested action is still pending ⏳ the server MUST also manage the status of the object that the command is about, so it reflects when the action starts and finishes 🚦 and once the action is done, all clients involved in the transaction MUST be notified with a service message that the action completed and the object's status changed 📣 main character energy for the server, iykyk 👑

3.2.1. EPP <create> Command

Okay bestie, the EPP <create> command is the transform operation that lets a client create a host object 🦋 Along with the usual EPP command elements, the <create> command MUST contain a <host:create> element that identifies the host namespace. That <host:create> element has these child elements:

  • A <host:name> element with the fully qualified name of the host object to be created.
  • Zero or more <host:addr> elements with the IP addresses to associate with the host. Each one MAY have an "ip" attribute to say which IP address format it uses. The value "v4" means IPv4 and "v6" means IPv6. If the "ip" attribute isn't specified, "v4" is the default 💖

Hosts can be provisioned as name servers in the Domain Name System (DNS), which is described in [RFC1034] and [RFC1035]. Hosts provisioned as name servers might be subject to server operator policies that require or prohibit specifying IP addresses, depending on the name of the host and the name space where the server will be used as a name server 👑 When a host is provisioned as a name server, IP addresses are REQUIRED only as needed to produce DNS glue records. For example, say the server is authoritative for the "com" name space and the server's name is "ns1.example.net". Then the server is not required to produce DNS glue records for the name server, and the DNS doesn't require IP addresses for the server. Lowkey iconic, right? 🌸

If the host name exists in a name space the server is authoritative for, then the superordinate domain of the host MUST be known to the server before the host object can be created. No skipping that step, periodt 💅

Example <create> command:

C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C:  <command>
C:    <create>
C:      <host:create
C:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
C:        <host:name>ns1.example.com</host:name>
C:        <host:addr ip="v4">192.0.2.2</host:addr>
C:        <host:addr ip="v4">192.0.2.29</host:addr>
C:        <host:addr ip="v6">1080:0:0:0:8:800:200C:417A</host:addr>
C:      </host:create>
C:    </create>
C:    <clTRID>ABC-12345</clTRID>
C:  </command>
C:</epp>

When a <create> command has been processed successfully, the EPP <resData> element MUST contain a child <host:creData> element that identifies the host namespace. That <host:creData> element has these child elements:

  • A <host:name> element with the fully qualified name of the host object.
  • A <host:crDate> element with the date and time the host object was created 🎀

Example <create> 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:      <host:creData
S:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
S:        <host:name>ns1.example.com</host:name>
S:        <host:crDate>1999-04-03T22:00:00.0Z</host:crDate>
S:      </host:creData>
S:    </resData>
S:    <trID>
S:      <clTRID>ABC-12345</clTRID>
S:      <svTRID>54322-XYZ</svTRID>
S:    </trID>
S:  </response>
S:</epp>

An EPP error response MUST be returned if a <create> command cannot be processed for any reason. No silent failures, bestie 😭

3.2.2. EPP <delete> Command

The EPP <delete> command is the transform operation that lets a client delete a host object 🧚 Along with the standard EPP command elements, the <delete> command MUST contain a <host:delete> element that identifies the host namespace. That <host:delete> element has this child element:

  • A <host:name> element with the fully qualified name of the host object to be deleted.

Okay, this one is a big deal 🙈 A host name object SHOULD NOT be deleted if it's associated with any other object. For example, if the host object is associated with a domain object, the host object SHOULD NOT be deleted until that association has been broken. Deleting a host object before breaking its existing associations can cause DNS resolution failure for domain objects that refer to the deleted host. Not me deleting the host and breaking everyone's DNS 💀

Example <delete> command:

C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C:  <command>
C:    <delete>
C:      <host:delete
C:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
C:        <host:name>ns1.example.com</host:name>
C:      </host:delete>
C:    </delete>
C:    <clTRID>ABC-12345</clTRID>
C:  </command>
C:</epp>

When a <delete> command has been processed successfully, a server MUST respond with an EPP response with no <resData> element. Clean exit, no drama ✨

Example <delete> 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:    <trID>
S:      <clTRID>ABC-12345</clTRID>
S:      <svTRID>54321-XYZ</svTRID>
S:    </trID>
S:  </response>
S:</epp>

An EPP error response MUST be returned if a <delete> command cannot be processed for any reason. 🫶

3.2.3. EPP <renew> Command

Renewal semantics don't apply to host objects, so there's no mapping defined for the EPP <renew> command. Nothing to renew here, bestie 🌈

3.2.4. EPP <transfer> Command

Transfer semantics don't directly apply to host objects, so there's no mapping defined for the EPP <transfer> command. Host objects are subordinate to an existing superordinate domain object, so they get transferred whenever a domain object is transferred. Hosts just go along for the ride 🦋

3.2.5. EPP <update> Command

The EPP <update> command is the transform operation that lets a client modify the attributes of a host object ✨ Along with the standard EPP command elements, the <update> command MUST contain a <host:update> element that identifies the host namespace. That <host:update> element has these child elements:

  • A <host:name> element with the fully qualified name of the host object to be updated.
  • An OPTIONAL <host:add> element with attribute values to be added to the object.
  • An OPTIONAL <host:rem> element with attribute values to be removed from the object.
  • An OPTIONAL <host:chg> element with object attribute values to be changed.

At least one <host:add>, <host:rem>, or <host:chg> element MUST be provided if the command is not being extended. All of these elements MAY be omitted if an <update> extension is present. The <host:add> and <host:rem> elements have these child elements:

  • One or more <host:addr> elements with IP addresses to be associated with or removed from the host object. The IP address restrictions from the <create> command mapping apply here too 🌸
  • One or more <host:status> elements with status values to be associated with or removed from the object. When you're removing a value, only the attribute value matters. The element text doesn't have to match a value to be removed.

A <host:chg> element has this child element:

  • A <host:name> element with a new fully qualified host name that the host object will be known by.

Host name changes MAY require adding or removing IP addresses for the server to accept them. IP address association MAY be subject to server policies for provisioning hosts as name servers 👑

Host name changes can affect associated objects that refer to the host object. A host name change SHOULD NOT require additional updates to associated objects in order to keep existing associations, with one exception: changing an external host object that has associations with objects sponsored by a different client. Attempts to update such hosts directly MUST fail with EPP error code 2305. The change can be provisioned by creating a new external host with a new name and the needed new attributes, then updating the other objects sponsored by the client. Main character energy, a whole migration plan 🧚

Example <update> command:

C:<?xml version="1.0" encoding="UTF-8" standalone="no"?>
C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
C:  <command>
C:    <update>
C:      <host:update
C:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
C:        <host:name>ns1.example.com</host:name>
C:        <host:add>
C:          <host:addr ip="v4">192.0.2.22</host:addr>
C:          <host:status s="clientUpdateProhibited"/>
C:        </host:add>
C:        <host:rem>
C:          <host:addr ip="v6">1080:0:0:0:8:800:200C:417A</host:addr>
C:        </host:rem>
C:        <host:chg>
C:          <host:name>ns2.example.com</host:name>
C:        </host:chg>
C:      </host:update>
C:    </update>
C:    <clTRID>ABC-12345</clTRID>
C:  </command>
C:</epp>

When an <update> command has been processed successfully, a server MUST respond with an EPP response with no <resData> element.

Example <update> 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:    <trID>
S:      <clTRID>ABC-12345</clTRID>
S:      <svTRID>54321-XYZ</svTRID>
S:    </trID>
S:  </response>
S:</epp>

An EPP error response MUST be returned if an <update> command could not be processed for any reason. Every failure gets a proper error response, no vibes-only rejections 💅

3.3. Offline Review of Requested Actions

Okay so, commands get processed by the server in the order the client sends them 📬. The server sends back an instant reply saying "got it and processed" ✨, but a server operator MAY do an offline review of transform commands before the requested action is actually finished. When that happens, the response from the server MUST clearly note that the transform command was received and processed, but the requested action is still pending ⏳. The status of the object MUST clearly reflect that pending action, and the server MUST notify the client once the offline processing is completed 🔔.

Here are some examples of a <create> command that needs offline review. Look closely at the result code and message that come back for the <create> command 👀.

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="1001">
S:      <msg>Command completed successfully; action pending</msg>
S:    </result>
S:    <resData>
S:      <host:creData
S:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
S:        <host:name>ns1.example.com</host:name>
S:        <host:crDate>1999-04-03T22:00:00.0Z</host:crDate>
S:      </host:creData>
S:    </resData>
S:    <trID>
S:      <clTRID>ABC-12345</clTRID>
S:      <svTRID>54322-XYZ</svTRID>
S:    </trID>
S:  </response>
S:</epp>

After this response, the host object's status MUST include "pendingCreate" 💅. The server operator reviews the request offline and lets the client know how it turned out, either by queuing a service message that the client can grab with the <poll> command 📥, or by using an out-of-band mechanism 🛸.

The service message MUST contain text in the <response>, <msgQ>, <msg> element that describes the notification 💬. On top of that, the EPP <resData> element MUST contain a child <host:panData> element that identifies the host namespace 🏷️. The <host:panData> element has these child elements:

  • A <host:name> element that holds the fully qualified name of the host object. This element has a REQUIRED "paResult" attribute 🎯. A positive boolean value means the request was approved and completed ✅. A negative boolean value means the request was denied and the requested action was not taken ❌.
  • A <host:paTRID> element that holds the client transaction identifier and server transaction identifier returned with the original response to the command 🔁. The client transaction identifier is OPTIONAL and only comes back if the client gave an identifier with the original <create> command 🙈.
  • A <host:paDate> element that holds the date and time when the review of the requested action was completed 📅.

Here's an example "review completed" service message 🎉:

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="1301">
S:      <msg>Command completed successfully; ack to dequeue</msg>
S:    </result>
S:    <msgQ count="5" id="12345">
S:      <qDate>1999-04-04T22:01:00.0Z</qDate>
S:      <msg>Pending action completed successfully.</msg>
S:    </msgQ>
S:    <resData>
S:      <host:panData
S:       xmlns:host="urn:ietf:params:xml:ns:host-1.0">
S:        <host:name paResult="1">ns1.example.com</host:name>
S:        <host:paTRID>
S:          <clTRID>ABC-12345</clTRID>
S:          <svTRID>54322-XYZ</svTRID>
S:        </host:paTRID>
S:        <host:paDate>1999-04-04T22:00:00.0Z</host:paDate>
S:      </host:panData>
S:    </resData>
S:    <trID>
S:      <clTRID>BCD-23456</clTRID>
S:      <svTRID>65432-WXY</svTRID>
S:    </trID>
S:  </response>
S:</epp>

4. Formal Syntax ✨

Okay, this part is the schema bestie 🤓. An EPP object mapping is written in XML Schema notation, and this is a complete schema for the mapping, so you can use it for automated validation of EPP XML instances 🤖. The BEGIN and END tags aren't part of the schema itself. They just mark where the schema starts and ends, which matters for URI registration purposes 🏁.

BEGIN
<?xml version="1.0" encoding="UTF-8"?>

<schema targetNamespace="urn:ietf:params:xml:ns:host-1.0"
       xmlns:host="urn:ietf:params:xml:ns:host-1.0"
       xmlns:epp="urn:ietf:params:xml:ns:epp-1.0"
       xmlns:eppcom="urn:ietf:params:xml:ns:eppcom-1.0"
       xmlns="http://www.w3.org/2001/XMLSchema"
       elementFormDefault="qualified">

<!--
Import common element types.
-->
 <import namespace="urn:ietf:params:xml:ns:eppcom-1.0"/>
 <import namespace="urn:ietf:params:xml:ns:epp-1.0"/>

 <annotation>
   <documentation>
     Extensible Provisioning Protocol v1.0
     host provisioning schema.
   </documentation>

 </annotation>

<!--
Child elements found in EPP commands.
-->
 <element name="check" type="host:mNameType"/>
 <element name="create" type="host:createType"/>
 <element name="delete" type="host:sNameType"/>
 <element name="info" type="host:sNameType"/>
 <element name="update" type="host:updateType"/>

<!--
Child elements of the <create> command.
-->
 <complexType name="createType">
   <sequence>
     <element name="name" type="eppcom:labelType"/>
     <element name="addr" type="host:addrType"
      minOccurs="0" maxOccurs="unbounded"/>
   </sequence>
 </complexType>

 <complexType name="addrType">
   <simpleContent>
     <extension base="host:addrStringType">
       <attribute name="ip" type="host:ipType"
        default="v4"/>
     </extension>
   </simpleContent>
 </complexType>

 <simpleType name="addrStringType">
   <restriction base="token">
     <minLength value="3"/>
     <maxLength value="45"/>
   </restriction>
 </simpleType>

 <simpleType name="ipType">
   <restriction base="token">
     <enumeration value="v4"/>
     <enumeration value="v6"/>
   </restriction>
 </simpleType>

<!--
Child elements of the <delete> and <info> commands.
-->

 <complexType name="sNameType">
   <sequence>
     <element name="name" type="eppcom:labelType"/>
   </sequence>
 </complexType>

<!--
Child element of commands that accept multiple names.
-->
 <complexType name="mNameType">
   <sequence>
     <element name="name" type="eppcom:labelType"
      maxOccurs="unbounded"/>
   </sequence>
 </complexType>
<!--
Child elements of the <update> command.
-->
 <complexType name="updateType">
   <sequence>
     <element name="name" type="eppcom:labelType"/>
     <element name="add" type="host:addRemType"
      minOccurs="0"/>
     <element name="rem" type="host:addRemType"
      minOccurs="0"/>
     <element name="chg" type="host:chgType"
      minOccurs="0"/>
   </sequence>
 </complexType>

<!--
Data elements that can be added or removed.
-->
 <complexType name="addRemType">
   <sequence>
     <element name="addr" type="host:addrType"
      minOccurs="0" maxOccurs="unbounded"/>
     <element name="status" type="host:statusType"
      minOccurs="0" maxOccurs="7"/>
   </sequence>
 </complexType>

<!--
Data elements that can be changed.
-->
 <complexType name="chgType">
   <sequence>
     <element name="name" type="eppcom:labelType"/>

   </sequence>
 </complexType>

<!--
Child response elements.
-->
 <element name="chkData" type="host:chkDataType"/>
 <element name="creData" type="host:creDataType"/>
 <element name="infData" type="host:infDataType"/>
 <element name="panData" type="host:panDataType"/>

<!--
<check> response elements.
-->
 <complexType name="chkDataType">
   <sequence>
     <element name="cd" type="host:checkType"
      maxOccurs="unbounded"/>
   </sequence>
 </complexType>

 <complexType name="checkType">
   <sequence>
     <element name="name" type="host:checkNameType"/>
     <element name="reason" type="eppcom:reasonType"
      minOccurs="0"/>
   </sequence>
 </complexType>

 <complexType name="checkNameType">
   <simpleContent>
     <extension base="eppcom:labelType">
       <attribute name="avail" type="boolean"
        use="required"/>
     </extension>
   </simpleContent>
 </complexType>

<!--
<create> response elements.
-->
 <complexType name="creDataType">
   <sequence>
     <element name="name" type="eppcom:labelType"/>
     <element name="crDate" type="dateTime"/>
   </sequence>
 </complexType>

<!--
<info> response elements.
-->
 <complexType name="infDataType">
   <sequence>
     <element name="name" type="eppcom:labelType"/>
     <element name="roid" type="eppcom:roidType"/>
     <element name="status" type="host:statusType"
      maxOccurs="7"/>
     <element name="addr" type="host:addrType"
      minOccurs="0" maxOccurs="unbounded"/>
     <element name="clID" type="eppcom:clIDType"/>
     <element name="crID" type="eppcom:clIDType"/>
     <element name="crDate" type="dateTime"/>
     <element name="upID" type="eppcom:clIDType"
      minOccurs="0"/>
     <element name="upDate" type="dateTime"
      minOccurs="0"/>
     <element name="trDate" type="dateTime"
      minOccurs="0"/>
   </sequence>
 </complexType>

<!--
Status is a combination of attributes and an optional human-readable
message that may be expressed in languages other than English.
-->
 <complexType name="statusType">
   <simpleContent>
     <extension base="normalizedString">
       <attribute name="s" type="host:statusValueType"
        use="required"/>
       <attribute name="lang" type="language"
        default="en"/>
     </extension>
   </simpleContent>
 </complexType>

 <simpleType name="statusValueType">
   <restriction base="token">
     <enumeration value="clientDeleteProhibited"/>
     <enumeration value="clientUpdateProhibited"/>
     <enumeration value="linked"/>
     <enumeration value="ok"/>
     <enumeration value="pendingCreate"/>
     <enumeration value="pendingDelete"/>
     <enumeration value="pendingTransfer"/>
     <enumeration value="pendingUpdate"/>
     <enumeration value="serverDeleteProhibited"/>
     <enumeration value="serverUpdateProhibited"/>
   </restriction>
 </simpleType>

<!--
Pending action notification response elements.
-->
 <complexType name="panDataType">
   <sequence>
     <element name="name" type="host:paNameType"/>
     <element name="paTRID" type="epp:trIDType"/>
     <element name="paDate" type="dateTime"/>
   </sequence>
 </complexType>
 <complexType name="paNameType">
   <simpleContent>
     <extension base="eppcom:labelType">
       <attribute name="paResult" type="boolean"
        use="required"/>
     </extension>
   </simpleContent>
 </complexType>

<!--
End of schema.
-->
</schema>
END

5. Internationalization Considerations ✨

okay so EPP is written in XML, and XML is giving full Unicode support 🌈 It natively handles the Unicode character set and its compact forms, including UTF-8. Conformant XML processors recognize both UTF-8 and UTF-16 [RFC2781]. XML can also use other character encodings if you set an "encoding" attribute in the <?xml?> declaration, but UTF-8 is RECOMMENDED in environments where parser encoding support is incompatible. bestie, just use UTF-8 🫶

All date-time values sent through EPP MUST be in Universal Coordinated Time using the Gregorian calendar 🕰️ XML Schema lets you use time zone identifiers for offsets from the zero meridian, but this option MUST NOT be used with EPP. The extended date-time form with upper case "T" and "Z" from [W3C.REC-xmlschema-2-20041028] MUST be used for date-time values, because XML Schema doesn't support truncated date-time forms or lower case "T" and "Z" characters. no lowercase, no shortcuts 💅

This document requires host name syntax as specified in [RFC0952] as updated by [RFC1123]. At the time of writing, RFC 3490 [RFC3490] describes a standard that uses certain ASCII name labels to represent non-ASCII name labels 🌸 These conformance requirements might change as the work on internationalized host names keeps moving forward, so keep an eye on it ✨

6. IANA Considerations 🦋

this document uses URNs to describe XML namespaces and XML schemas that follow a registry mechanism described in [RFC3688]. IANA has registered two URI assignments.

Registration request for the host namespace:

URI: urn:ietf:params:xml:ns:host-1.0

Registrant Contact: See the "Author's Address" section of this
document.

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

Registration request for the host XML schema:

URI: urn:ietf:params:xml:schema:host-1.0

Registrant Contact: See the "Author's Address" section of this
document.

XML: See the "Formal Syntax" section of this document.

7. Security Considerations 🔐😭

okay this one is short but it's SERIOUS 💀 The object mapping in this document does not provide any security services, and it doesn't add any extra considerations beyond what [RFC4930] and the protocol layers EPP uses already cover. so if you need security, the protocols underneath are where it lives 🫶 don't assume this mapping is doing the heavy lifting 🙅‍♀️

8. Acknowledgements 🎀

this document started life as an individual submission Internet-Draft. The PROVREG working group later adopted it as a working group document and gave loads of invaluable comments and suggested improvements 👑 The author wants to thank WG chairs Edward Lewis and Jaap Akkerhuis for their process and editorial contributions 💜

specific suggestions that made it into this document came from Chris Bason, Jordyn Buchanan, Dave Crocker, Anthony Eden, Sheer El-Showk, Klaus Malorny, Dan Manley, Michael Mealling, Patrick Mevzek, and Rick Wesson 🙌 literally the whole squad 🥹

9. References 📚

9.1. Normative References

[RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791,
           September 1981.

[RFC0952]  Harrenstien, K., Stahl, M., and E. Feinler, "DoD Internet
           host table specification", RFC 952, October 1985.

[RFC1034]  Mockapetris, P., "Domain names - concepts and facilities",
           STD 13, RFC 1034, November 1987.

[RFC1035]  Mockapetris, P., "Domain names - implementation and
           specification", STD 13, RFC 1035, November 1987.

[RFC1123]  Braden, R., "Requirements for Internet Hosts - Application
           and Support", STD 3, RFC 1123, October 1989.

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

[RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
           January 2004.

[RFC4291]  Hinden, R. and S. Deering, "IP Version 6 Addressing
           Architecture", RFC 4291, February 2006.

[RFC4930]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)",
           RFC 4930, May 2007.

[W3C.REC-xml-20040204]
           Yergeau, F., Maler, E., Sperberg-McQueen, C., Bray, T.,
           and J. Paoli, "Extensible Markup Language (XML) 1.0 (Third
           Edition)", World Wide Web Consortium FirstEdition REC-xml-
           20040204, February 2004,
           <http://www.w3.org/TR/2004/REC-xml-20040204>.

[W3C.REC-xmlschema-1-20041028]
           Thompson, H., Maloney, M., Mendelsohn, N., and D. Beech,
           "XML Schema Part 1: Structures Second Edition", World Wide
           Web Consortium Recommendation REC-xmlschema-1-20041028,
           October 2004,
           <http://www.w3.org/TR/2004/REC-xmlschema-1-20041028>.

[W3C.REC-xmlschema-2-20041028]
           Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes
           Second Edition", World Wide Web Consortium
           Recommendation REC-xmlschema-2-20041028, October 2004,
           <http://www.w3.org/TR/2004/REC-xmlschema-2-20041028>.

9.2. Informative References

[RFC1886]  Thomson, S. and C. Huitema, "DNS Extensions to support IP
           version 6", RFC 1886, December 1995.

[RFC2781]  Hoffman, P. and F. Yergeau, "UTF-16, an encoding of ISO
           10646", RFC 2781, February 2000.

[RFC2874]  Crawford, M. and C. Huitema, "DNS Extensions to Support
           IPv6 Address Aggregation and Renumbering", RFC 2874,
           July 2000.

[RFC3152]  Bush, R., "Delegation of IP6.ARPA", BCP 49, RFC 3152,
           August 2001.

[RFC3490]  Faltstrom, P., Hoffman, P., and A. Costello,
           "Internationalizing Domain Names in Applications (IDNA)",
           RFC 3490, March 2003.

[RFC3732]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
           Host Mapping", RFC 3732, March 2004.

Appendix A. Changes from RFC 3732 🧾

okay this is the glow-up log 💅 here's everything that changed from RFC 3732:

  1. Minor reformatting. The I-D source went from nroff to XML 🖥️
  2. Removed this text from Section 2.3:
"Transform commands MUST be rejected when a pendingCreate,
pendingDelete, pendingTransfer, or pendingUpdate status is set."
  1. Changed text in Section 3.2.2. It used to say this:
"A host name object MUST NOT be deleted if the host object is
associated with any other object.  For example, if the host
object is associated with a domain object, the host object MUST
NOT be deleted until the existing association has been broken."

and now it says this:

"A host name object SHOULD NOT be deleted if the host object is
associated with any other object.  For example, if the host
object is associated with a domain object, the host object SHOULD
NOT be deleted until the existing association has been broken.
Deleting a host object without first breaking existing
associations can cause DNS resolution failure for domain objects
that refer to the deleted host object."
  1. Changed text in Section 3.2.5 from:
"At least one <host:add>, <host:rem>, or <host:chg> element MUST be provided."

to:

"At least one <host:add>, <host:rem>, or <host:chg> element MUST be
provided if the command is not being extended.  All of these
elements MAY be omitted if an <update> extension is present."
  1. Changed text in Section 3.3 (old Section 3.2.6) from this:
"The server operator reviews the request offline, and informs the
client of the outcome of the review by queuing a service message
for retrieval via the <poll> command."

to this:

"The server operator reviews the request offline, and informs the
client of the outcome of the review either by queuing a service
message for retrieval via the <poll> command or by using an out-
of-band mechanism to inform the client of the request."
  1. Removed the text describing use of the XML Schema schemaLocation attribute. It's optional and doesn't need to be mandated for EPP 🙌
  2. Removed references to RFC 3339 and replaced them with references to the W3C XML Schema specification 🔄
  3. Replaced references to RFC 3513 with references to RFC 4291 🔁
  4. Updated EPP and XML references 🆙

Author's Address 🌷

Scott Hollenbeck
VeriSign, Inc.
21345 Ridgetop Circle
Dulles, VA  20166-6503
US

EMail: shollenbeck@verisign.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 🧠

The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.

Acknowledgement 💖

Funding for the RFC Editor function is currently provided by the Internet Society. 🫶

📦 where this page comes from