RFC 5732

Extensible Provisioning Protocol (EPP) Host Mapping

📅 published August 2009, from ietf

RFC 5732: Extensible Provisioning Protocol (EPP) Host Mapping 🎀

okay bestie, so this is RFC 5732 🧚 It's an Internet Standards Track doc (STD 69) from the Network Working Group, written by S. Hollenbeck at VeriSign, Inc., and it's dated August 2009. It obsoletes RFC 4932, and it doesn't list any updates. The whole point is defining how EPP handles host names stored in a shared central repository, and it's written in XML 💖

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 .............................................6
      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 ............................25
   6. IANA Considerations ............................................25
   7. Security Considerations ........................................26
   8. Acknowledgements ...............................................26
   9. References .....................................................26
      9.1. Normative References ......................................26
      9.2. Informative References ....................................27
   Appendix A.  Changes from RFC 4932 ................................29

Abstract ✨

so the abstract is basically the elevator pitch 💅 This doc describes an Extensible Provisioning Protocol (EPP) mapping for provisioning and managing Internet host names that live in a shared central repository. It's specified in XML, and the mapping defines EPP command syntax and semantics as they apply to host names. And yes, it obsoletes RFC 4932.

Status of This Memo 📜

this one is giving "official stamp" energy 🫶 It specifies an Internet standards track protocol for the Internet community and asks for discussion and suggestions for improvements. To find the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited.

Copyright Notice 🌸

Copyright (c) 2009 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 in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, since they describe your rights and restrictions with respect to this document.

1. Introduction 🦋

okay so this section sets the scene. The document describes an Internet host name mapping for version 1.0 of the Extensible Provisioning Protocol (EPP). The mapping is written in the Extensible Markup Language (XML) 1.0, as described in [W3C.REC-xml-20040204], and uses XML Schema notation as described in [W3C.REC-xmlschema-1-20041028] and [W3C.REC-xmlschema-2-20041028]. It obsoletes RFC 4932 [RFC4932] 🎀

[RFC5730] gives the complete rundown of EPP command and response structures, so you really need to understand that base protocol spec before the mapping in this doc will make sense 🧠

XML is case sensitive, bestie. Unless stated otherwise, XML specifications and examples in this document MUST be interpreted in the character case presented, so you can build a conforming implementation.

1.1. Relationship of Host Objects and Domain Objects 🍓

this is the big one for how hosts and domains relate 💅 The document assumes host name objects have a subordinate relationship to a superordinate domain name object. For example, the host name ns1.example.com is subordinate to the domain name example.com. EPP actions (like object transfers) that don't 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, 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 spec, since the name of the host doesn't belong to the namespace of the repository where it's being used for delegation.

Whether a host is external or internal depends on the repository where it's being used for delegation 🙈 An internal host is subordinate if its name belongs to the domain within that 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 still 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 the examples, "C:" means lines sent by a protocol client, and "S:" means lines returned by a protocol server 🧚 Indentation and white space are only there to show how elements relate, so they are NOT a REQUIRED feature of this protocol. (Lowercase is just for vibes here, not a requirement!)

2. Object Attributes 🎀

an EPP host object has attributes and associated values that the sponsoring client or the server can view and modify ✨ This section breaks down each attribute type. You'll find the formal syntax for these attribute values in the "Formal Syntax" section of this document and in the appropriate normative references.

2.1. Host Names 💖

the syntax for host names in this doc MUST conform to [RFC0952] as updated by [RFC1123]. As 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 later as internationalized host name standards keep progressing 👑

2.2. Client Identifiers 🫶

all EPP clients get identified by a server-unique identifier 💅 Client identifiers conform to the "clIDType" syntax described in [RFC5730].

2.3. Status Values 🔥

okay this is a whole thing bestie 😭 A host object MUST always have at least one associated status value. Status values MAY be set only by the client that sponsors the 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 come with a string of human-readable text explaining why that status was 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 because 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 a server can add or remove are prefixed with "server". Status values that don't begin with either "client" or "server" are server-managed 🦋

Here's the status value rundown:

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, for a <transfer> command, for the host object's superordinate domain object), but the action hasn't been completed by the server yet. Server operators can delay action completion for a variety of reasons, such as allowing 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 is completed, the pendingCreate, pendingDelete, pendingTransfer, or pendingUpdate status value MUST be removed 🌸 All clients involved in the transaction MUST be notified with a service message that the action has been completed and that the object's status has changed.

the combo rules are next, and they're kinda strict 🙈

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 not 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. XML Schema doesn't support truncated date-time forms or lower case "T" and "Z" characters, so that's why it's like this 💅

2.5. IP Addresses 💜

the IPv4 address syntax in this doc MUST conform to [RFC0791]. The IPv6 address syntax MUST conform to [RFC4291]. Practical stuff about publishing IPv6 address info in zone files is documented in [RFC2874] and [RFC3596]. A server MAY reject IP addresses that haven't 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 ✨

okay so the full EPP syntax and semantics live over in [RFC5730] 💅 this section is just the part about using EPP to provision and manage Internet host names 🌐

3.1. EPP Query Commands 🔍

EPP gives you two commands to pull host info. <check> tells you whether a host object can be provisioned in a repository, and <info> gets you the detailed stuff about a host object 🧚

3.1.1. EPP `<check>` Command

The EPP <check> command is how you ask whether an object can be provisioned in a repository 🫶 It's basically a hint so a client can guess if a <create> is gonna work, since provisioning rules are ultimately up to server policy 🙈

In addition to the standard EPP command elements, the <check> command MUST contain a <host:check> element that identifies the host namespace. The <host:check> element has these child elements:

One or more <host:name> elements that contain the fully qualified names of the host objects to be queried.

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 has been processed successfully, the EPP <resData> element MUST contain a child <host:chkData> element that identifies the host namespace. The <host:chkData> element contains one or more <host:cd> elements, and each of those has these child elements:

A <host:name> element that contains the fully qualified name of the queried host object. This element MUST contain an "avail" attribute whose value tells you whether the object is available (can it be provisioned or not) at the moment the <check> command was completed. A value of "1" or "true" means the object can be provisioned. A value of "0" or "false" means the object cannot be provisioned. 🎀
An OPTIONAL <host:reason> element that MAY be provided when an object cannot be provisioned. If it's there, it holds server-specific text explaining why the object can't be provisioned. This text MUST be represented in the response language previously negotiated with the client. An OPTIONAL "lang" attribute MAY be present to identify the language if the negotiated value is something other than the default value of "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 cannot be processed for any reason. 🚨

3.1.2. EPP `<info>` Command

The EPP <info> command is for retrieving information about a host object 📦 In addition to the standard EPP command elements, the <info> command MUST contain a <host:info> element that identifies the host namespace. The <host:info> element has these child elements:

A <host:name> element that contains 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 has been processed successfully, the EPP <resData> element MUST contain a child <host:infData> element that identifies the host namespace. The <host:infData> element has these child elements:

A <host:name> element that contains the fully qualified name of the host object.
A <host:roid> element that contains the Repository Object IDentifier 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 that contain the IP addresses associated with the host object.
A <host:clID> element that contains the identifier of the sponsoring client.
A <host:crID> element that contains the identifier of the client that created the host object.
A <host:crDate> element that contains the date and time the host object was created.
A <host:upID> element that contains the identifier of the client that last updated the host object. This element MUST NOT be present if the host object has never been modified.
A <host:upDate> element that contains the date and time of the most recent host-object modification. This element MUST NOT be present if the host object has never been modified.
A <host:trDate> element that contains the date and time of the most recent successful host-object transfer. This element MUST NOT be provided if the host object has never been transferred. Note that host objects MUST NOT be transferred directly. Host objects MUST be transferred implicitly when the host object's superordinate domain object is transferred. Host objects that are subject to transfer when transferring a domain object are listed in the response to an EPP <info> command performed on the 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 cannot be processed for any reason. 💀

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 🙅‍♀️

3.2. EPP Transform Commands 🛠️

EPP has three commands that transform host objects: <create> makes an instance of a host object, <delete> deletes one, and <update> changes the info attached to one. This document does not define host-object mappings for the EPP <renew> and <transfer> commands 💅

Transform commands are usually processed and completed in real time. Server operators MAY receive and process transform commands but defer completing the requested action if human or third-party review is required before it can be completed. In that situation, the server MUST return a 1001 response code to the client to note that the command has been received and processed but that the requested action is pending. The server MUST also manage the status of the object that is the subject of the command, so it reflects the start and finish of the requested action. Once the action is completed, all clients involved in the transaction MUST be notified, using a service message, that the action has been completed and that the object's status has changed. Other notification methods MAY be used in addition to the required service message. 🔔

Server operators SHOULD confirm that a client is authorized to perform a transform command on a given object. Any attempt to transform an object by an unauthorized client MUST be rejected, and the server MUST return a 2201 response code to the client to note that the client lacks the privileges to execute the requested command. 🚫

3.2.1. EPP <create> Command ✨

okay bestie, the EPP <create> command is the transform op that lets a client make a host object 🎀 In addition to the standard EPP command elements, the <create> command MUST contain a <host:create> element that identifies the host namespace. Inside <host:create> you get these child elements:

A <host:name> element with the fully qualified name of the host object being created 💖
Zero or more <host:addr> elements with the IP addresses that go with the host. Each one MAY have an "ip" attribute to say which address format it is. "v4" means IPv4 and "v6" means IPv6. If you don't include "ip", it defaults to "v4" 🌸

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 IP addresses, depending on the host name and the namespace where the server is used as a name server. So lowkey it depends. When you provision a host as a name server, IP addresses are REQUIRED only as needed to produce DNS glue records. For example, if the server is authoritative for the "com" namespace and its name is "ns1.example.net", the server is not required to produce DNS glue records for that name server, and the DNS doesn't require IP addresses for it either 🦋

If the host name exists in a namespace 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 this 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. The <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>

If a <create> command can't be processed for any reason, an EPP error response MUST be returned. No silent failures, bestie 🙈

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

3.2.2. EPP <delete> Command 🫶

The EPP <delete> command is another transform op, and it lets a client delete a host object. In addition to the standard EPP command elements, the <delete> command MUST contain a <host:delete> element that identifies the host namespace. The <host:delete> element has one child element:

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

A host object SHOULD NOT be deleted if it 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 that association has been broken. Deleting a host object without breaking the existing associations first can cause DNS resolution failure for the domain objects that refer to it. Yikes, so don't be that person 😭

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 🌈

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 is no mapping defined for the EPP <renew> command. Not every command is for every object, and that's totally fine 💜

3.2.4. EPP <transfer> Command 🧚

Transfer semantics don't directly apply to host objects, so there is 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 gets transferred. It's giving "the host goes where the domain goes" 🏡

3.2.5. EPP <update> Command 🎀

The EPP <update> command is the transform op for modifying the attributes of a host object. In addition to the standard EPP command elements, the <update> command MUST contain a <host:update> element that identifies the host namespace. The <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 for removal to work 🔥

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

A <host:name> element with a new fully qualified host name for the host object to be known by 👑

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

Host name changes can have an impact on objects that refer to the host object. A host name change SHOULD NOT require extra updates to associated objects to keep the existing associations, with one exception: changing an external host object that has associations with objects sponsored by a different client. Trying to update those 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 any needed new attributes, and then updating the other objects the client sponsors. Main character glow-up, no drama 💅

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.

3.3. Offline Review of Requested Actions ✨

Okay bestie, so the server handles commands in the order the client sends them 💅 It sends back an instant response saying "got it, processing" 📨, but a server operator MAY perform an offline review of transform commands before actually finishing the requested action. This is legit, not me being dramatic 💀 When it happens, the response MUST clearly say the transform command was received and processed, BUT the requested action is still pending ⏳ The object's status MUST clearly reflect that pending action too. And once offline processing is done, the server MUST notify the client 🔔

Here's a <create> command that needs offline review, so peep the result code and message in the 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="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 that response, the host object's status MUST include pendingCreate 🫶 The server operator reviews the request offline and lets the client know the outcome, either by queuing a service message you can grab with the <poll> command, or through an out-of-band mechanism 📬

The service message MUST contain text describing the notification in the child <msg> element of the response <msgQ> element. 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 with 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 it was denied and the requested action was not taken. 💖
A <host:paTRID> element holding the client transaction identifier and server transaction identifier that came back with the original response to process the command. The client transaction identifier is OPTIONAL and only gets returned if the client gave one with the original <create> command. 🎀
A <host:paDate> element with the date and time when 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 bestie, this part is the schema 🎀. EPP object mappings are written in XML Schema notation, and this is the complete schema for the host object mapping, so validators can check EPP XML instances automatically 🔥. The BEGIN and END lines are NOT part of the schema. They just mark where the schema starts and ends for URI registration purposes 💅.

Here's the license, verbatim, because legal stuff gets no glow-up 🫶:

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Internet Society, IETF or IETF Trust, nor the names of specific contributors, may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Here's the schema itself 🧚:

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 comes with native Unicode support 🌸. The compact version is UTF-8, which is honestly iconic. Conformant XML processors recognize both UTF-8 and UTF-16 [RFC2781]. XML can also handle other character encodings through an encoding attribute in an <?xml?> declaration, but using UTF-8 is RECOMMENDED in environments where parser encoding support is incompatible 🫶.

All date-time values presented via EPP MUST be expressed in Universal Coordinated Time using the Gregorian calendar ⏰. XML Schema lets you use time zone identifiers for offsets from the zero meridian, but that option MUST NOT be used with EPP 🙅. The extended date-time form, with upper case "T" and "Z" characters as defined in [W3C.REC-xmlschema-2-20041028], MUST be used to represent date-time values. XML Schema doesn't support truncated date-time forms or lower case "T" and "Z" characters, so this is the only way to go 💅.

The syntax for domain and host names described in this document MUST conform to [RFC0952] and [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 as work on internationalized host name standards moves forward, so keep an eye on this one, bestie 👀.

6. IANA Considerations 📋

this section is all about registrations 🎀. 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 ✨.

Here's the 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.

And here's the 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, serious moment, bestie 😭. The object mapping in this document does not provide any security services, and it doesn't introduce any extra considerations beyond the ones described in [RFC5730] or the ones caused by the protocol layers EPP uses 💀. So security lives in those other specs, not here, periodt 🙈.

8. Acknowledgements ✨

RFC 3732 is a product of the PROVREG working group, and they were so generous with improvements and invaluable comments 🫶. The author wants to give a big shout-out to WG chairs Edward Lewis and Jaap Akkerhuis for their process and editorial contributions 👑. RFC 4932 and this document are individual submissions, both built on the work done in RFC 3732 🌸.

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 💖. Iconic contributors, all of them 💅.

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.

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

[W3C.REC-xml-20040204]
           Sperberg-McQueen, C., Maler, E., Yergeau, F., Paoli, J.,
           and T. Bray, "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]
           Maloney, M., Thompson, H., 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]
           Malhotra, A. and P. Biron, "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

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

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

[RFC3596]  Thomson, S., Huitema, C., Ksinant, V., and M. Souissi,
           "DNS Extensions to Support IP Version 6", RFC 3596,
           October 2003.

[RFC4932]  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)
           Host Mapping", RFC 4932, May 2007.

Appendix A. Changes from RFC 4932 🦋

Okay, so this appendix is basically the changelog between RFC 4932 and this document, and it's giving very organised energy 🗂️. Here's everything that changed:

Changed "This document obsoletes RFC 3732" to "This document obsoletes RFC 4932".
Replaced references to RFC 1886 with references to 3596.
Removed references to RFC 3152 since both it and 1886 have been obsoleted by 3596.
Replaced references to RFC 3732 with references to 4932.
Replaced references to RFC 4930 with references to 5730.
Added "Other notification methods MAY be used in addition to the required service message" in Section 3.2.
Added 2201 response code text in Section 3.2.
Added BSD license text to XML schema section.

Item 6 is the one to notice 👀. The word MAY there is a real requirement keyword, so it stays in capitals and keeps its exact force 💜.

Author's Address 💌

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

EMail: shollenbeck@verisign.com

That's the whole RFC, bestie! 🌈💖✨

📦 where this page comes from

ietf: rfc5732 2009-08
💖 girlified by claude-haiku-5-5 on 2026-10-17: a language model's rewrite of the original, under its terms