Provisioning Registry Protocol Working Group Hong Liu Internet-Draft Ning Zhang Document: Tom McGarry Category: Standard Track NeuStar, Inc. Expires January 2003 August, 2002 Uniform Treatment of Pending Action Notification in EPP A Strawman Proposal Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract Many domain registries, especially sponsored TLDs and ccTLDs, have specific policy that calls for the server to perform additional backend processing before it completes a transform operation on an object requested by a client. When the pending action is completed, the server must notify the client about the outcome. However, current EPP core specifications do not address the notification messaging in a generic way. As a result, a registry has to resort to defining a new schema as extension to the object mapping concerned for this purpose. Inspired by recent discussions on the "ietf-provreg" mailing list on related topics, this draft presents a strawman proposal for uniform treatment of server notification for pending action in the base EPP protocol. A new OPTIONAL child element is added to response as Expires January 2003 [Page 1] Internet-Draft EPP Pending Action Notify August 2002 basic notification content, which consists of the transaction ID that triggered the pending action and the outcome of the pending action. In addition, object specific data and extension information can be piggybacked in existing child elements of . The required modification to the EPP base protocol is kept to the minimum and incurs no change to the EPP base object mappings. Most importantly, the proposed solution is applicable to any object mapping, ensuring EPP's extensibility beyond domain registry applications. Strong interests by the registry community in deploying this feature warrant that it be best handled as a generic but optional feature in the EPP base protocol. This allows any registry to handle pending action without the need to define a new schema, eliminating the proliferation of ad hoc object extensions repetitively defined by disparate registries for the very same purpose. 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 is provided only to show element relationships and is not a REQUIRED feature of the protocol. Table of Contents 1. Introduction ................................................. 3 2. Background Information ....................................... 4 2.1 The "Infamous" Pending Operation ............................ 4 2.2 Handling Pending Action ..................................... 5 2.3 Design Principles and Requirements .......................... 6 3. Solving the Notification Problem ............................. 7 3.1 Deciding the Notification Content ........................... 7 3.2 Placing Notification in Response Message .................... 9 3.3 Summary of the Proposal ..................................... 10 3.4 Formal Syntax for Proposed Changes .......................... 11 4. An Illustrative Example ...................................... 12 5. Internationalization Considerations .......................... 15 6. IANA Considerations .......................................... 15 7. Security Considerations ...................................... 15 8. Acknowledgements ............................................. 15 9. References ................................................... 16 10. Authors' Addresses .......................................... 17 A. Revisions From Previous Version .............................. 17 B. Full Copyright Statement ..................................... 18 Expires January 2003 [Page 2] Internet-Draft EPP Pending Action Notify August 2002 1. Introduction Many domain registries, especially sponsored gTLDs and ccTLDs, have specific policy that calls for the server to perform additional backend processing before it completes a transform operation (e.g., create, delete, update, renew, and transfer) on an object requested by a client. When the pending action is completed, the server must notify the client about the success or failure of the pending action. This capability is also highly desirable for some unsponsored gTLDs that want to deploy advanced registry services. However, except for the transfer command, which is specially treated in EPP, the current EPP core specifications [EPP,DOMAIN,CONTACT,HOST] do not sufficiently address the notification messaging in a generic way for other transform commands. As a result, registries that need to use this capability for those commands on a specific object mapping have to resort to defining new schemas of their own as an EPP extension to the object mapping concerned [COOP]. Since these schemas (or at least part of the schema) are designed for the same purpose, they are similar in function but different in XML syntax. This draft presents a strawman proposal for uniform treatment of server notification for pending action in EPP. By abstracting this capability to the EPP base protocol, the proposal allows a registry to handle pending action without the need to define a new schema, eliminating the proliferation of registry-specific schemas for the very same purpose. The required modification to the EPP base protocol is kept to the minimum and incurs no change to existing object mapping schemas. Most importantly, the proposal is applicable to any object mapping, existing or to be defined, ensuring EPP's extensibility beyond domain registry applications. The proposal is inspired by recent discussions on the "ietf-provreg" mailing list on related topics (THREAD1,THREAD2,THREAD3). The authors strongly believe that this capability warrants a uniform treatment at the EPP base protocol due to strong interests from a large registry community. The proposal is intended to serve a starting point towards a generic solution to the problem at hand. It is expected that the outcome of this draft will be included in the final version of the EPP base protocol specification [EPP]. In this draft, the EPP base protocol refers to specification [EPP], the EPP base object mappings refer to specifications for domain, contact and host objects [DOMAIN,CONTACT,HOST], and the EPP core specifications consists of all four documents plus the TCP transport document [EPP-TCP]. Expires January 2003 [Page 3] Internet-Draft EPP Pending Action Notify August 2002 2. Background Information Recent discussions [THREAD3] on IESG's proposed changes to the EPP core specifications have led to a debate on whether pending operation should be supported by EPP and how server notification should be done if it is supported. While the first issue seems to be resulting from the confusion about terminology and moving towards a resolution to keeping the capability, the second issue remains open. This draft is a contribution to the second issue. This section aims at highlighting the key points in this debate. In particular, it gives a precise definition of "pending action", discusses the lack of uniform treatment for server notification messaging in EPP, and identifies the set of design principles and functional requirements for solving the problem. It sets the stage for our proposal presented in Section 3. 2.1 The "Infamous" Pending Operation The IETF extensible provision protocol (EPP) is a client/server protocol for client to provision objects in the server. The primary working mode is that a client initiates a command and the server responds. In most cases, the simple command/response exchange completes the action requested by the client's command. However, in some cases, the server needs to perform additional backend processing before the action is completed. The transfer operation already defined in EPP is a good example of the latter case. Another example is that in many sponsored gTLDs and ccTLDs, a domain registration will not be approved by the registry until further checking is done by the backend [COOP]. A "pending action" is normally caused by a transform operation on an object by the client that requires additional backend processing. In this draft, a transform operation refers to create, delete, update, or renew. Transfer is not covered in this draft since its processing is already defined in EPP. So a pending action could be a pending create/delete/update/renew operation on an object. Note: for lack of better term, we use "pending action" instead of "pending operation" due to the negative connotation the latter embodied during the WG list discussion [THREAD3]. Any suggestion of a better term is welcome. A typical client/server interaction involving additional server backend processing is a four-step exchange: - The client sends a command to the server requesting an operation to be performed on an object. Expires January 2003 [Page 4] Internet-Draft EPP Pending Action Notify August 2002 - The server responds to the client that the command has been successfully received and processed, pending additional backend processing. - The server completes the pending action and puts the result as a notification message to the client in the server's message queue. - The client polls the server and gets the final result of the requested operation. It is important to note that in the second step, the server merely signals to the client that it needs additional processing in order to complete the client's request. Although at this point, the command/ response transaction is considered complete in EPP, the requested action is not, for both the client and the server. It is not until in step 4 is the client notified about the outcome of the requested action. So the client must keep track of the state of the action until after step 4. It is generally agreed by the Provreg WG that the client MUST NOT perform additional transform operations on an object with a pending action [THREAD2]. 2.2 Handling Pending Action Pending action handling in EPP consists of the following three aspects: - A set of object status codes denoting an object's pending state. - A new result code for the server to inform the client in the initial response that the requested action is pending. - A notificaiton mechanism for the server to inform the client of the result of a pending action when it is completed. The first aspect is resolved by the EPP base object mappings, with the addition of a few new status codes proposed in [THREAD2]. Now each EPP base object mapping is equipped with the following status code related to pending action: "pendingVerification" (for create), "pendingDelete", and "pendingUpdate". "pendingRenew" is not defined yet, but could be included if the WG finds it useful. The second aspect is handled by including a new result code XXXX (to be assigned) "Command completed successfully; action pending" in the EPP base protocol, as accepted by the WG in [THREAD2]. As for the third aspect, it is clear that the server will put the pending action result in the message queue, and the client will be able to retrieve it using the procedures in [EPP]. What is not Expires January 2003 [Page 5] Internet-Draft EPP Pending Action Notify August 2002 clear is how the notification information is encoded and where it should be placed in the element. Before we get into the solution space in Section 3, we outline the set of design principles and functional requirements for handling pending action notification in EPP. 2.3 Design Principles and Requirements At a high level, pending action handling in EPP SHALL adhere to the following design principles: - OPTIONAL: a registry SHALL be able to decide whether it makes use of this capability or not. - GENERIC: it SHALL be defined in the EPP core, i.e., a registry SHALL be able to support this capability without the need to define a new EPP schema as extension to an object mapping. - SIMPLE: any modification incurred in the EPP core SHALL be kept to the minimum to reduce cost and to ensure smooth upgrade. - UNIFORM: it SHALL work for any transform operation on any object type defined in a registry. - FLEXIBLE: a registry SHALL be able to decide, on an individual basis, which transform operation on what object type that needs this capability On a detailed level, any solution to pending action notification SHALL satisfy the following functional requirements. It SHALL - uniquely identify to the client the original transaction that triggers the pending action. - uniquely identify to the client the object on which the pending action is perform. - notify the client the success or failure of the pending action. - allow provision of OPTIONAL object specific data - allow provision of OPTIONAL object specific extension data Here object specific data refers to an object mapping defined in the registry, such as EPP base object mappings, or any new object mapping existing or to be defined for EPP. Object extension data refers to registry-specific data that are defined as extension to an existing object mapping. Expires January 2003 [Page 6] Internet-Draft EPP Pending Action Notify August 2002 3. Solving the Notification Problem Based on the discussions in Section 2, the problem to be solved is the format of response for pending action notification in the EPP base protocol. Specifically, two questions need to be answered: - What are the information elements in a notification content? - Where is the notification message specified in the response? In the following, we will look for answers to these two problems in turn. 3.1 Deciding the Notification Content According to the functional requirements in Section 2.3, it should be sufficient that the notification content contains the following information elements: - the transaction ID that triggers the pending action. The transaction ID is a tuple (clTRID,svTRID). clTRID is the OPTIONAL client transaction ID that, when present in the triggering client command, uniquely identifies the triggering transaction on the client side. svTRID is the server transaction ID that is sent back to the client in the response to the triggering command. It uniquely identifies the triggering transaction on the server side. Do not confuse the tuple with the one in the element. The latter is the transaction ID for the command-response exchange. So this tuple should be specified as new elements in the notification content. - the object ID on which the pending action is performed. The object ID, denoted as objID, uniquely identifies an object in a registry. It is used here to identified the object involved in the pending action. In the context of EPP base object mappings, for domain object, it is the domain name; for contact object, it is the contact ID; and for host object, it is the host name. New object ID types may also be defined for other object mappings. This item can be specified as a new element in the notification content. - the outcome of the pending action. This can be specified as a new boolean attribute of the notification content, with "1" for success and "0" for failure. Expires January 2003 [Page 7] Internet-Draft EPP Pending Action Notify August 2002 - optionally, any object specific data. This can be provisioned in the element of . No new element needs to be defined for notification purpose. - optionally, any object specific extension data This can be provisioned in the element of . No new element needs to be defined for notification purpose. So far, the new EPP element ("pa" for pending action) that needs to be defined for notification content contains three child elements (, , ) and one boolean attribute . But it can be further simplified in a number of ways in that the three child elements are somewhat overlapping for the purpose of identifying the pending action and the object involved. Following the SIMPLE design principle in Section 2.3, under certain conditions, we can reduce the number of elements to one (let it be ): - Option 1: use svTRID only. This assumes that both the server and the client cache svTRID for each pending action. - Option 2: use clTRID only. This requires that clTRID be mandatory for all transform commands in EPP. However, it seems that the WG will keep it as OPTIONAL for EPP commands in the EPP base protocol. So clTRID alone will not be sufficient to identify the triggering transaction. It also assume that both the server and the client cache the clTRID for each pending action. - Option 3: use objID only. This requires that at most one pending action be allowed on each object in EPP. While it is not yet clarified in EPP, it seems to be a sensible requirement to be added in the EPP base protocol. It also assume that both the server and the client cache the objID for each pending action. Among the three options, Option 1 seems to be the least intrusive as it does not incur any additional change in the EPP core. Option 3 is also a good candidate when the at most one pending action per object requirement is added in the EPP base protocol. However, the XML type definition for is simpler in Option 1 than in Option 3: type is in Option 1 but is the union of and in Option 3. More importantly, future EPP object mappings may define new objID types that are different from either or . To ensure extensibility without changing type definition, has to be defined as "any" type in XML for Option 2. This is bad as it introduces dependency to other object Expires January 2003 [Page 8] Internet-Draft EPP Pending Action Notify August 2002 mappings. This is exactly what we try to avoid by the UNIFORM design principle. Following the SIMPLE and UNIFORM design principles, Option 1 is choosen as the pending action ID in this draft. From the preceding anaylsis, the basic notification content encoded in consists of the following (minimum) information: - A element of type , taking the value of the server transaction ID for the triggering transaction of the pending action. - A boolean attribute to indicate the result of the pending action, with "1" for success and "0" for failure. Using , a registry will be able to provide uniform treatment of pending action notificatoin in EPP regardless of the transform command and the object type. What is left is where to put the element in the response message. 3.2 Placing Notification in Response Message To use response to convey server notification to the client, we need to place the notification content in the element. We already talked about the placement of optional notification content: - the OPTIONAL object specific data in , and - the OPTIONAL object extension specific data in Both of and are OPTIONAL child elements of already defined in the EPP base protocol. As for placing the basic notification content in , there are a couple of options: - add as an OPTIONAL child element of , or - add as an OPTIONAL child element of in . Since semantically, is designed for returning the result of the command in the response (in this case, the command, not the triggering command for the pending action), it seems better to place as a direct child element in instead. This is the approach taken in this draft. Expires January 2003 [Page 9] Internet-Draft EPP Pending Action Notify August 2002 3.3 Summary of the Proposal To summarize, our strawman proposal for uniform treatment of pending action handling consists of the following key points: - Pending action handling is defined as an integral part of the EPP base protocol, not as an EPP extension. It is an OPTIONAL capability offered by the EPP base protocol. Registries will be able to use this capability without the need to define a new schema, eliminating the proliferation of EPP extension schemas for this purpose. - Pending action is uniformly handled for any transform operation over any EPP object mapping. It is up to a registry to decide which transform operation on what object type would need additional backend processing. The proposed changes are independent of any EPP object mapping schema, making it applicable to any (existing or to be defined) object mapping in addition to those already defined as EPP base object mappings. - The server signals to a client's command that triggers a pending action by returning a result code XXXX "Command completed successfully; action pending" in the response to the triggering command. The exact value of the new result code is to be assigned in the next revision of the EPP base protocol specification. - Both the server and the client cache the server transaction ID from the element of the server response to the triggering command. Its value will be taken for in the notification content to uniquely identify the triggering transaction when the pending action is completed. - The server notification content consists of two parts: basic and optional. The basic notification content is REQUIRED in any pending action handling. The optional notification content allows additional object specific data and object specific extension data to be provisioned in the notification using the and child elements already defined in , respectively. This achieves extensibility via reuse. - The basic notification content is encoded in the element, which is a new OPTIONAL child element of . The structure is purposely kept simple: one element that uniquely identifies the triggering transaction of the pending action; and one boolean attribute that indicates the result of the pending action, with "1" for success and "0" for failure. represents the minimum information required for any pending action notification in EPP. Expires January 2003 [Page 10] Internet-Draft EPP Pending Action Notify August 2002 It should not be difficult to show that our proposed solution abides by the design principles and satisfies the functional requirements listed in Section 2.3. 3.4 Formal Syntax for Proposed Changes This section defines the formal syntax of the proposed changes to the EPP base schema "epp-1.0.xsd". Only the changes incurred by this proposal are highlighted for ease of reference, other existing definitions are omitted.

Expires January 2003 [Page 11] Internet-Draft EPP Pending Action Notify August 2002 4. An Illustrative Example In this section, we use the command of domain object mapping as an example to show how pending action is handled in EPP using our proposal. A step-by-step EPP message flow is presented. This is one of the most common use cases that require pending action handling among various domain registries. Suppose the registry requires additional backend processing when a domain name is first created. The following is a typical sequence of client/server interactions resulting from the initial command for the requested domain. (1) The client sends a command to register a new domain "example.tld": C: C: C: C: C: C: example.tld C: 2fooBAR C: C: C: ABC-12345 C: C: (2) The server responds to the command as currently defined in EPP base protocol, except that the action needs additional backend processing. So it returns the result code XXXX (to be assigned in EPP) "Command completes successfully; action pending" instead. Internally, the server sets the status of "example.tld" domain object to "pendingVerification". It shall also cache the svTRID as the key to the stored pending action record. S: S:

Expires January 2003 [Page 12] Internet-Draft EPP Pending Action Notify August 2002 S: S: S: Command completed successfully; action pending S: S: S: S: example.tld S: 1999-04-03T22:00:00.0Z S: S: S: S: ABC-12345 S: 54321-XYZ S: S: S:

At this point, the client shall cache the from the response and use it as the key to the stored pending action record. No further action shall be performed on domain "example.tld" by the client until it gets the notification from the server regarding the pending action. (3) When the server finishes backend processing, it puts the result as a notification in the message queue. The notification contains only the basic content. The value of is the server transation ID for the triggering transaction. If the server grants the registration request, it sets the value of attribute to "1"; otherwise it sets the value to "0". Assume that the registration is approved, the value of attribute is set to "1". (4) The client in a later time issues a command to retrieve the notification: C: C: C: C: C: BCD-23456 C: C:

Expires January 2003 [Page 13] Internet-Draft EPP Pending Action Notify August 2002 (5) The server recognizes that the message at the head of the queue is for pending action notication. It responds to a command by including as a child element of . S: S: S: S: S: Command completed successfully; message dequeued S: S: S: 2000-06-08T22:00:00.0Z S: Pending action completed successfully. S: S: S: 54321-XYZ S: S: S: BCD-23456 S: 65432-WXY S: S: S: (6) The client retrieves from the response. It uses to retrieve the pending action record, and finds out it is for the registration request of domain "example.tld". Since is "1", it knows that the registration has been approved. (7) The client and server completes the ack and ack response. On the server side, the message is dequeued and the pending action record is removed. On the client side, the pending action record is removed. At this point, the pending action is considered complete on both sides. Expires January 2003 [Page 14] Internet-Draft EPP Pending Action Notify August 2002 5. Internationalization Considerations This draft does not introduce or present any internationalization or localization issues beyond those specified in the EPP base protocol specification [EPP]. 6. IANA Considerations This draft does not introduce or present any new IANA considerations beyond those specified in the EPP base protocol specification [EPP]. 7. Security Considerations This draft does not provide any other security services or introduce any additional considerations beyond those described in the EPP base protocol specification [EPP]. 8. Acknowledgements The authors will like to thank many people for contributing ideas and comments that led to the writing of this document, either on the "ietf-provreg" mailing list or via private communications. Special thanks go to Scott Hollenbeck, Patrik Falstrom, Rick Wesson, Dan Manley, Robert Burbidge, Bruce Tonkin, and Janusz Sienkiewicz for sharing their insights on this topic. We apologize if we miss anyone. Expires January 2003 [Page 15] Internet-Draft EPP Pending Action Notify August 2002 9. References [EPP] Hollenbeck, S., "Extensible Provisioning Protocol", Internet- Draft , work in progress. [DOMAIN] Hollenbeck, S., "Extensible Provisioning Protocol Domain Name Mapping", Internet-Draft , work in progress. [CONTACT] Hollenbeck, S., "Extensible Provisioning Protocol Contact Mapping", Internet-Draft , work in progress. [HOST] Hollenbeck, S., "Extensible Provisioning Protocol Host Mapping", Internet-Draft , work in progress. [EPP-TCP] Hollenbeck, S., "Extensible Provisioning Protocol Transport over TCP", Internet-Draft , work in progress. [RFC793] Postel, J., "Transmission Control Protocol", STD 7, RFC 793, September 1981. [RFC2119] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [THREAD1] IETF Provreg WG mailing list thread "Pending Update", http://www.cafax.se/ietf-provreg/maillist/2002-02/msg00035.html. [THREAD2] IETF Provreg WG mailing list thread "Additional Response Code and Status Code for EPP", http://www.cafax.se/ietf-provreg/maillist/2002-03/msg00006.html. [THREAD3] IETF Provreg WG mailing list thread "RE: Proposed Document Changes - Pending Operations ", http://www.cafax.se/ietf-provreg/maillist/2002-07/msg00028.html. [COOP] Poptel Limited, "EPP Extension for the .coop TLD Registrant Verification", http://www.coop/downloads/registrars/EppExtensionsForDotCoop.pdf, work in progress. Expires January 2003 [Page 16] Internet-Draft EPP Pending Action Notify August 2002 10. Authors' Addresses Hong Liu NeuStar, Inc. Loudoun Tech Center 46000 Center Oak Plaza Sterling, VA 20166 U.S.A. Email: hong.liu@neustar.biz Ning Zhang NeuStar, Inc. Loudoun Tech Center 46000 Center Oak Plaza Sterling, VA 20166 U.S.A. Phone: +1-571-434-5583 Email: ning.zhang@neustar.biz Tom McGarry NeuStar, Inc. Loudoun Tech Center 46000 Center Oak Plaza Sterling, VA 20166 U.S.A. Email: tom.mcgarry@neustar.biz A. Revisions From Previous Version TBD Expires January 2003 [Page 17] Internet-Draft EPP Pending Action Notify August 2002 B. Full Copyright Statement Copyright (C) The Internet Society 2001. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS 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. Acknowledgement Funding for the RFC editor function is currently provided by the Internet Society. Expires January 2003 [Page 18]