Extensible Provisioning Protocol (EPP) Domain Name MappingStatus 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 Notice
Copyright (C) The IETF Trust (2007).Abstract
This document describes an Extensible Provisioning Protocol (EPP) mapping for the provisioning and management of Internet domain names stored in a shared central repository. Specified in XML, the mapping defines EPP command syntax and semantics as applied to domain names. This document obsoletes RFC 3731.
Hollenbeck Standards Track [Page 1]
RFC 4931 EPP Domain Name Mapping May 2007Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Relationship of Domain Objects and Host Objects . . . . . 3 1.2. Conventions Used in This Document . . . . . . . . . . . . 5 2. Object Attributes . . . . . . . . . . . . . . . . . . . . . . 5 2.1. Domain and Host Names . . . . . . . . . . . . . . . . . . 5 2.2. Contact and Client Identifiers . . . . . . . . . . . . . . 5 2.3. Status Values . . . . . . . . . . . . . . . . . . . . . . 5 2.4. Dates and Times . . . . . . . . . . . . . . . . . . . . . 7 2.5. Validity Periods . . . . . . . . . . . . . . . . . . . . . 8 2.6. Authorization Information . . . . . . . . . . . . . . . . 8 2.7. Other DNS Resource Record Attributes . . . . . . . . . . . 8 3. EPP Command Mapping . . . . . . . . . . . . . . . . . . . . . 9 3.1. EPP Query Commands . . . . . . . . . . . . . . . . . . . . 9 3.1.1. EPP Hollenbeck Standards Track [Page 2] RFC 4931 EPP Domain Name Mapping May 20071. Introduction This document describes an Internet domain name mapping for version 1.0 of the Extensible Provisioning Protocol (EPP). This mapping is specified using the Extensible Markup Language (XML) 1.0 as described in [W3C.REC-xml-20040204] and XML Schema notation as described in [W3C.REC-xmlschema-1-20041028] and [W3C.REC-xmlschema-2-20041028]. This document obsoletes RFC 3731 [RFC3731]. [RFC4930] provides a complete description of EPP command and response structures. A thorough understanding of the base protocol specification is necessary to understand the mapping described in this document. XML is case sensitive. Unless stated otherwise, XML specifications and examples provided in this document MUST be interpreted in the character case presented to develop a conforming implementation.1.1. Relationship of Domain Objects and Host Objects The EPP mapping for host objects is described in [RFC4932]. This document assumes that domain name objects have a superordinate relationship to subordinate host name objects. For example, domain name \"example.com\" has a superordinate relationship to host name \"ns1.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 for which 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. Such hosts are described as \"external\" hosts in this specification since the name of the host does not belong to the name space of the repository in which the host is being used for delegation purposes. Whether a host is external or internal relates to the repository in which the host is being used for delegation purposes. Whether or not an internal host is subordinate relates to 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. Name server hosts for domain delegation can be specified as either references to existing host objects or as domain attributes that describe a host machine. A server operator MUST use one name server Hollenbeck Standards Track [Page 3] RFC 4931 EPP Domain Name Mapping May 2007 specification form consistently. A server operator that announces support for host objects in an EPP greeting MUST NOT allow domain attributes to describe a name server host machine. A server operator that does not announce support for host objects MUST allow domain attributes to describe a name server host machine. When domain attributes are used to describe a name server host machine, IP addresses SHOULD be required only as needed to generate DNS glue records. Name servers are specified within a element MUST contain one or more - Zero or more OPTIONAL Attribute value \"v6\" is used to note IPv6 address format. If the \"ip\" attribute is not specified, \"v4\" is the default attribute value. IP address syntax requirements are described in Section 2.5 of the EPP host mapping [RFC4932]. Example host object name server elements for domain example.com: Example host attribute name server elements for domain example.com: Hollenbeck Standards Track [Page 4] RFC 4931 EPP Domain Name Mapping May 20071.2. Conventions Used in This Document The key words \"MUST\ \"SHOULD\ document are to be interpreted as described in [RFC2119]. In examples, \"C:\" represents lines sent by a protocol client and \"S:\" represents lines returned by a protocol server. Indentation and white space in examples are provided only to illustrate element relationships and are not a REQUIRED feature of this protocol.2. Object Attributes An EPP domain 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. Domain and Host Names The syntax for domain and 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 to use certain ASCII name labels to represent non-ASCII name labels. These conformance requirements might change as a result of progressing work in developing standards for internationalized domain names. A server MAY restrict allowable domain names to a particular top-level domain, second-level domain, or other domain for which the server is authoritative. The trailing dot required when these names are stored in a DNS zone is implicit and MUST NOT be provided when exchanging host and domain names. 2.2. Contact and Client Identifiers All EPP contacts are identified by a server-unique identifier. Contact identifiers are character strings with a specified minimum length, a specified maximum length, and a specified format. Contact identifiers use the \"clIDType\" client identifier syntax described in [RFC4930].2.3. Status Values A domain object MUST always have at least one associated status value. Status values can be set only by the client that sponsors a domain object and by the server on which the object resides. A client can change the status of a domain object using the EPP Hollenbeck Standards Track [Page 5] RFC 4931 EPP Domain Name Mapping May 2007 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 can be added or removed by a client are prefixed with \"client\". Corresponding status values that can be added or removed by a server are prefixed with \"server\". Status values that do not begin with either \"client\" or \"server\" are server-managed. Status Value Descriptions: - clientDeleteProhibited, serverDeleteProhibited Requests to delete the object MUST be rejected. - clientHold, serverHold DNS delegation information MUST NOT be published for the object. - clientRenewProhibited, serverRenewProhibited Requests to renew the object MUST be rejected. - clientTransferProhibited, serverTransferProhibited Requests to transfer the object MUST be rejected. - clientUpdateProhibited, serverUpdateProhibited Requests to update the object (other than to remove this status) MUST be rejected. - inactive Delegation information has not been associated with the object. - 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. Hollenbeck Standards Track [Page 6] RFC 4931 EPP Domain Name Mapping May 2007 - pendingCreate, pendingDelete, pendingRenew, pendingTransfer, pendingUpdate A transform command has been processed for the 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, pendingRenew, 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 MUST NOT be combined with any other status. \"pendingDelete\" status MUST NOT be combined with either \"clientDeleteProhibited\" or \"serverDeleteProhibited\" status. \"pendingRenew\" status MUST NOT be combined with either \"clientRenewProhibited\" or \"serverRenewProhibited\" status. \"pendingTransfer\" status MUST NOT be combined with either \"clientTransferProhibited\" or \"serverTransferProhibited\" status. \"pendingUpdate\" status MUST NOT be combined with either \"clientUpdateProhibited\" or \"serverUpdateProhibited\" status. The pendingCreate, pendingDelete, pendingRenew, 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 defined in [W3C.REC-xmlschema-2-20041028] MUST be used to represent date-time values as XML Schema does not support truncated date-time forms or lower case \"T\" and \"Z\" characters. Hollenbeck Standards Track [Page 7] RFC 4931 EPP Domain Name Mapping May 20072.5. Validity Periods A domain name object MAY have a specified validity period. If server policy supports domain object validity periods, the validity period is defined when a domain object is created, and it MAY be extended by the EPP policy, this specification does not define actions to be taken upon expiration of a domain object’s validity period. Validity periods are measured in years or months with the appropriate units specified using the \"unit\" attribute. Valid values for the \"unit\" attribute are \"y\" for years and \"m\" for months. The minimum allowable period value is one (1). The maximum allowable value is ninety-nine decimal (99). A server MAY support a lower maximum value. 2.6. Authorization Information Authorization information is associated with domain objects to facilitate transfer operations. Authorization information is assigned when a domain object is created, and it might be updated in the future. This specification describes password-based authorization information, though other mechanisms are possible.2.7. Other DNS Resource Record Attributes While the DNS allows many resource record types to be associated with a domain, this mapping only explicitly specifies elements that describe resource records used for domain delegation and resolution. Facilities to provision other domain-related resource record types can be developed by extending this mapping. The provisioning method described in this mapping separates discrete data elements by data type. This method of data definition allows XML Schema processors to perform basic syntax validation tasks, reducing ambiguity and the amount of parsing and syntax-checking work required of protocol processors. Provisioning and extension methods that aggregate data into opaque strings are possible, but such methods SHOULD NOT be used because they impose additional parsing, interpretation, and validation requirements on protocol processors. Hollenbeck Standards Track [Page 8] RFC 4931 EPP Domain Name Mapping May 20073. 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 use in provisioning and managing Internet domain names via EPP.3.1. EPP Query Commands EPP provides three commands to retrieve domain information: repository, The EPP In addition to the standard EPP command elements, the - One or more C: C: C: C: Hollenbeck Standards Track [Page 9] RFC 4931 EPP Domain Name Mapping May 2007 When a contains one or more - A completed. A value of \"1\" or \"true\" means that the object can be provisioned. A value of \"0\" or \"false\" means that the object can not be provisioned. - An OPTIONAL 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 S: S: S: S: S: S: S: S: S: Hollenbeck Standards Track [Page 10] RFC 4931 EPP Domain Name Mapping May 2007 S: An EPP error response MUST be returned if a The EPP authorization information, and server policy towards unauthorized clients. If the querying client is the sponsoring client, all available information MUST be returned. If the querying client is not the sponsoring client, but the client provides valid authorization information, all available information MUST be returned. If the querying client is not the sponsoring client, and the client does not provide valid authorization information, server policy determines which OPTIONAL elements are returned. In addition to the standard EPP command elements, the - A information describing only delegated hosts. A value of \"sub\" returns information describing only subordinate hosts. A value of \"none\" returns no information describing delegated or subordinate hosts. - An OPTIONAL associated contacts. An OPTIONAL \"roid\" attribute MUST be used to identify the registrant or contact object if and only if the given authInfo is associated with a registrant or contact object, and not the domain object itself. If this element is not provided or if the authorization information is invalid, server policy determines if the command is rejected or if response information will be returned to the client. Hollenbeck Standards Track [Page 11] RFC 4931 EPP Domain Name Mapping May 2007 Example C: C: Example C: C: C: When an - A - A Hollenbeck Standards Track [Page 12] RFC 4931 EPP Domain Name Mapping May 2007 - Zero or more OPTIONAL - If supported by the server, one OPTIONAL - An OPTIONAL servers) associated with the domain object. See Section 1.1 for a description of the elements used to specify host objects or host attributes. - Zero or more OPTIONAL - A - An OPTIONAL - An OPTIONAL - An OPTIONAL - An OPTIONAL - An OPTIONAL Hollenbeck Standards Track [Page 13] RFC 4931 EPP Domain Name Mapping May 2007 - An OPTIONAL Example S: S: S: S: S: S: S: S: S: S: S: S: S: Hollenbeck Standards Track [Page 14] RFC 4931 EPP Domain Name Mapping May 2007 A server with a different information return policy MAY provide less information in a response. Example S: S: S: S: S: S: An EPP error response MUST be returned if an 3.1.3. EPP The EPP transfer requests. In addition to the standard EPP command elements, the - A - An OPTIONAL associated contacts. An OPTIONAL \"roid\" attribute MUST be used to identify the registrant or contact object if and only if the given authInfo is associated with a registrant or contact object, and Hollenbeck Standards Track [Page 15] RFC 4931 EPP Domain Name Mapping May 2007 not the domain object itself. If this element is not provided or if the authorization information is invalid, server policy determines if the command is rejected or if response information will be returned to the client. Example C: C: C: C: C: When a - A - A - A - A - A Hollenbeck Standards Track [Page 16] RFC 4931 EPP Domain Name Mapping May 2007 - A before an automated response action will be taken by the server. For all other status types, the value identifies the date and time when the request was completed. - An OPTIONAL S: S: S: S: S: S: S: S: S: An EPP error response MUST be returned if a EPP provides five commands to transform domain objects: Hollenbeck Standards Track [Page 17] RFC 4931 EPP Domain Name Mapping May 2007 Transform commands are typically 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 the requested action can be completed. In such situations the server MUST return a 1001 response code to the client to note that the command has been received and processed, but the requested action is pending. The server MUST also manage the status of the object that is the subject of the command to reflect the initiation and completion of the requested action. Once the action has been completed, 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.3.2.1. EPP The EPP - A - An OPTIONAL - An OPTIONAL servers) associated with the domain object to provide resolution services for the domain; see Section 1.1 for a description of the elements used to specify host objects or host attributes. A host object MUST be known to the server before the host object can be associated with a domain object. - An OPTIONAL identifier for the human or organizational social information (contact) object to be associated with the domain object as the object registrant. This object identifier MUST be known to the server before the contact object can be associated with the domain object. The EPP mapping for contact objects is described in [RFC4933]. Hollenbeck Standards Track [Page 18] RFC 4931 EPP Domain Name Mapping May 2007 - Zero or more OPTIONAL - A information to be associated with the domain object. This mapping includes a password-based authentication mechanism, but the schema allows new mechanisms to be defined in new schemas. Example C: C: C: C: C: C: C: C: When a - A - A Hollenbeck Standards Track [Page 19] RFC 4931 EPP Domain Name Mapping May 2007 - An OPTIONAL Example S: S: S: S: S: S: S: An EPP error response MUST be returned if a The EPP - A A domain object SHOULD NOT be deleted if subordinate host objects are associated with the domain object. For example, if domain \"example.com\" exists, and host object \"ns1.example.com\" also exists, then domain \"example.com\" SHOULD NOT be deleted until host \"ns1.example.com\" has been either deleted or renamed to exist in a different superordinate domain. A server SHOULD notify clients that object relationships exist by sending a 2305 error response code when Hollenbeck Standards Track [Page 20] RFC 4931 EPP Domain Name Mapping May 2007 a with a domain object can be determined using the C: C: C: C: When a S: S: S: S: S: An EPP error response MUST be returned if a The EPP Hollenbeck Standards Track [Page 21] RFC 4931 EPP Domain Name Mapping May 2007 contain a namespace. The - A - A - An OPTIONAL Example C: C: C: C: C: When a - A - An OPTIONAL Hollenbeck Standards Track [Page 22] RFC 4931 EPP Domain Name Mapping May 2007 Example S: S: S: S: S: S: S: An EPP error response MUST be returned if a The EPP - A - An OPTIONAL