Internet Engineering Task Force Hong Liu Internet-Draft Ning Zhang Tom McGarry Richard Wilhelm NeuStar, Inc. September 2002 Expires: March 2003 Extensible Provisioning Protocol Over SOAP 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 This memo documents a proposal for exchanging EPP (Extensible Provisioning Protocol) messages as XML documents between a client and a server via SOAP (Simple Object Access Protocol), using the SOAP request/response communication model. An EPP message is encapsulated in the SOAP Body, while the EPP session information is encoded in the SOAP header, enabling EPP session-oriented messaging over the SOAP protocol. It is designed to work on top of any transport bindings defined for SOAP, taking advantage of the variety of SOAP software tools and environments available for web services. 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 [1]. Hong Liu, et al Expires March 2003 [Page 1] Internet-Draft EPP Over SOAP September 2002 Table of Contents 1. Introduction ................................................. 3 2. EPP Over SOAP ................................................ 5 2.1 Message Identification ...................................... 5 2.2 Message Format .............................................. 5 2.3 Message Processing .......................................... 16 2.4 Session Management .......................................... 17 3. Formal Syntax ................................................ 18 4. Internationalization Considerations .......................... 20 5. IANA Considerations .......................................... 20 6. Security Considerations ...................................... 20 7. Acknowledgements ............................................. 21 8. References ................................................... 21 9. Authors' Addresses ........................................... 23 A. Revisions From Previous Version .............................. 24 B. Full Copyright Statement ..................................... 24 Hong Liu, et al Expires March 2003 [Page 2] Internet-Draft EPP Over SOAP September 2002 1. Introduction The Extensible Provisioning Protocol (EPP) [2] defines generic object management operations and an extensible framework that maps protocol operations to objects stored in a shared central repository. The Simple Object Access Protocol (SOAP) [7, 8] defines light-weight messaging protocol for implementing a wide variety of distributed messaging models. Both protocols are based on XML [12] and use XML Schema [13, 14] for message format definition. This memo documents a proposal for exchanging EPP messages via SOAP in a request/response fashion between an EPP client and an EPP server. It uses the SOAP envelope mechanism to encapsulate EPP messages as XML documents in the SOAP Body exchanged between two SOAP nodes [7, 8] using the SOAP request/response communication model. As a result, all existing EPP object mappings [3, 4, 5] and future object mappings and extensions can be supported on top of SOAP without any change. In addition, there are no data encoding (i.e., serialization or marshalling) issues [8] involved for EPP over SOAP. Both the EPP server and an EPP client play the roles of a SOAP sender and a SOAP receiver, depending on the message direction. While it is possible to have SOAP intermediaries between an EPP client and the EPP server, this memo does not use this SOAP feature, nor does it exclude its use in the future. The SOAP receiver, be it the EPP server or an EPP client, assumes the "ultimateReceiver" role in the SOAP message exchange path. That is, it is the SOAP node that is responsible to process the EPP session information in the SOAP Header and the EPP message in the SOAP Body. SOAP is silent on how state information is maintained. Generally, session related information are encoded in the SOAP Header and/or the SOAP Body to be handled by the application logic sitting behind the SOAP protocol front-end. On the other hand, EPP's primary working mode is session-oriented. To bridge the semantic gap between the two protocols, the concept of "virtual session" is utilized using the SOAP Header to encode EPP session information. This session header is used by both the EPP server and an EPP client to correlate SOAP messages belonging to the same session. Like EPP, SOAP also requires a transport binding. Currently, HTTP [8] and Email [9] are the two transport bindings defined by W3C, and BEEP transport binding is defined in IETF as RFC 3288 [10]. HTTP seems to be the most prevalent one in use. Some SOAP toolkits also support other forms of transport such as raw TCP. This memo assumes no specific transport binding for SOAP. Instead, it is intended to be applicable to all transport bindings available for SOAP to expand the transport options for EPP. This allows EPP to be transported beyond Hong Liu, et al Expires March 2003 [Page 3] Internet-Draft EPP Over SOAP September 2002 just TCP [6], without the need to define new transport bindings already defined for SOAP. It also allows registry and registrar software developers to take advantage of the variety of software tools and environments made available for web services. Throughout this memo, the terms of "SOAP Header", "SOAP Body" and "SOAP Fault" are defined in Section 5 of [7]. In examples, "C:" represents lines sent by an EPP client and "S:" represents lines returned by an EPP server. Indentation and white space in examples is provided only to show element relationships and is not a REQUIRED feature of the proposal. This memo is being discussed on the "ietf-provreg" mailing list. To join the list, send a message to with the words "subscribe ietf-provreg" in the body of the message. There is a web site for the list archives at http://www.cafax.se/ietf-provreg. Hong Liu, et al Expires March 2003 [Page 4] Internet-Draft EPP Over SOAP September 2002 2. EPP Over SOAP 2.1 Message Identification If media type "application/soap+xml", as defined in [11], is used for recognizing SOAP messages, the OPTIONAL "action" parameter is RECOMMENDED be set with the EPP namespace value: urn:ietf:params:xml:ns:epp-1.0 specified in [2], for identifying the intent of the SOAP messages exchanged between an EPP client and an EPP server. 2.2 Message Format All EPP messages exchanged between an EPP client and an EPP server via SOAP MUST be embedded in the SOAP Body. Upon a successful EPP session establishment via a valid EPP command, the SOAP Header MUST contain an element for each message exchanged subsequently, including in the first EPP response to a successful EPP command. The element MUST contain a "mustUnderstand" attribute with value "true". An element contains the following child elements: - A element that contains the client identifier used for establishing the EPP session via an EPP command. - A element that contains the server-assigned session identifier. The session identifier value MAY be changed as the session progresses (see below). An EPP client MUST use the identifier assigned by the server in subsequent SOAP requests sent to the server until the server changes the session identifier. - An OPTIONAL element that contains the new server- assigned session identifier. This element, if appears, SHOULD only be in SOAP messages from the server. When a client receives a SOAP message from the server, if this element appears in the SOAP header, it MUST replace the current session identifier, as appears in , with the value of this element and MUST use it in any subsequent SOAP messages sent to the server during this session until the server changes the session identifier again. This element MUST only be set by the server. A client MUST NOT use this element in the SOAP header in SOAP messages sent to the server. The server SHOULD ignore this element in any message from a client. Hong Liu, et al Expires March 2003 [Page 5] Internet-Draft EPP Over SOAP September 2002 - An OPTIONAL element that contains the session expiration timestamp. This element MUST be returned by an EPP server in the SOAP responses after a successful EPP session establishment. It MUST NOT be specified by an EPP client in any SOAP requests. The value MAY be extended as the session progresses. This element MUST only be set by the server. A client MUST NOT use this element in the SOAP header in SOAP messages sent to the server. The server SHOULD ignore this element in any message from a client. In what follows, we present EPP over SOAP message examples, following the steps outlined in Sections 2.3 and 2.4, to show how EPP messages encapsulated in the SOAP envelope flow between the server and a client. (1) The client initiates an EPP session with the server by first sending the EPP message. C: C: C: C: C: C: C: C: C: C: Note that a SOAP message enclosing an EPP message in the SOAP Body but without the element in the SOAP Header signals to the server that the client intends to open up a new EPP session with the server. This is different than any message sent by the client after the session is established, where the SOAP Header contains the session information element (see below). (2) The server responds to the client with the EPP message, listing the object mappings and options it supports for the session. S: S: Hong Liu, et al Expires March 2003 [Page 6] Internet-Draft EPP Over SOAP September 2002 S: S: S: S: S: S: Example EPP server epp.example.tld S: 2002-09-27T22:00:00.0Z S: S: 1.0 S: en S: fr S: urn:ietf:params:xml:ns:obj1 S: urn:ietf:params:xml:ns:obj2 S: urn:ietf:params:xml:ns:obj3 S: S: http://custom/obj1ext-1.0 S: http://custom/obj2ext-1.0 S: S: S: S: S: S: S: S: S: S: S: S: S: S: Note that the message sent by the server for session setup is different from the one sent after the session is established. The former does not have the session information in the SOAP Header, while the latter has (see below). (3) The client negotiates the session options with the server by sending the EPP command. C: C: C: C: Hong Liu, et al Expires March 2003 [Page 7] Internet-Draft EPP Over SOAP September 2002 C: S: C: C: C: ClientX C: foo-BAR2 C: bar-FOO2 C: C: 1.0 C: en C: C: C: urn:ietf:params:xml:ns:obj1 C: urn:ietf:params:xml:ns:obj2 C: C: http://custom/obj1ext-1.0 C: C: C: C: ABC-12345 C: C: C: C: (4) The server checks the login credentials of the client, prepares the session options, and responds to the client that the session has been successfully established. In particular, the EPP session information is encoded in the SOAP header. This is the first SOAP message that carries the session information between the server and the client for this session. From this point and on, the session information should be carried in all subsequent SOAP messages exchanges between the server and the client until the session is terminated or expires. S: S: S: S: S: ClientX S: NV0x12aNX3YTAsdK Hong Liu, et al Expires March 2003 [Page 8] Internet-Draft EPP Over SOAP September 2002 S: 2002-09-30T23:59:59.0Z S: S: S: S: S: S: S: S: Command completed successfully S: S: S: S: S: S: S: S: S: (5) At the receipt of the response, the client knows that it has successfully established the session. The session identifier assigned by the server is "NV0x12aNX3YTAsdK" and the session is valid until 23:59:59 GMT on September 30, 2002. The client should use the same session identifier for all subsequent SOAP messages sent to the server, until the server changes the session identifier or the session is terminated or expires. Suppose after the session is set up, the client sends an EPP command for a few domains to the server, the SOAP message looks like the following: C: C: C: C: C: ClientX C: NV0x12aNX3YTAsdK C: C: C: C: S: C: C: C: C: example1.tld C: example2.tld C: example3.tld C: C: C: ABC-12345 C: C: C: C: The SOAP message for the server response to the command looks like the following: S: S: S: S: S: ClientX S: NV0x12aNX3YTAsdK S: 2002-09-30T23:59:59.0Z S: S: S: S: S: S: S: S: Command completed successfully S: S: Hong Liu, et al Expires March 2003 [Page 10] Internet-Draft EPP Over SOAP September 2002 S: S: S: example1.tld S: S: S: example1.tld S: In use S: S: S: example3.tld S: S: S: S: S: ABC-12345 S: 54322-XYZ S: S: S: S: S: A noted earlier, any message sent by the client after the session is set up should carry the session information. C: C: C: C: C: ClientX C: NV0x12aNX3YTAsdK C: C: C: C: C: BCD-23456 C: Hong Liu, et al Expires March 2003 [Page 11] Internet-Draft EPP Over SOAP September 2002 C: C: The message returned by the server during the session should also carry the session information. S: S: S: S: S: ClientX S: NV0x12aNX3YTAsdK S: 2002-09-30T23:59:59.0Z S: S: S: S: S: S: S: Example EPP server epp.example.tld S: 2002-09-28T18:30:29.0Z S: S: 1.0 S: en S: fr S: urn:ietf:params:xml:ns:obj1 S: urn:ietf:params:xml:ns:obj2 S: urn:ietf:params:xml:ns:obj3 S: S: http://custom/obj1ext-1.0 S: http://custom/obj2ext-1.0 S: S: S: S: S: S: S: S: S: Hong Liu, et al Expires March 2003 [Page 12] Internet-Draft EPP Over SOAP September 2002 S: S: S: S: S: (6) At some point before the session expires, the client may choose to close the session by sending the server an EPP command: C: C: C: C: C: ClientX C: NV0x12aNX3YTAsdK C: C: C: C: C: CDE-34567 C: C: C: The server responds to the client to terminate the session. S: S: S: S: S: ClientX S: NV0x12aNX3YTAsdK S: 1970-01-01T00:00:00.0Z S: S: S: Hong Liu, et al Expires March 2003 [Page 13] Internet-Draft EPP Over SOAP September 2002 S: S: S: S: S: Command completed successfully S: S: S: CDE-34567 S: 76543-OPQ S: S: S: S: S: Note that the child element of in the SOAP Header has changed value to a past date of the current date, indicating that the session information is no longer valid for the client on the server side. Any subsequent SOAP message carrying the old session information will be rejected by the server, as explained next. (8) If the client sends a SOAP message with session information that the server has no knowledge of, the server will reject the SOAP message with an EPP response using the EPP result code 2200 "Authentication error". This response MUST NOT contain any session information in the SOAP Header. S: S: S: S: S: S: S: S: S: Authentication error S: S: S: EFG-23456 S: 98765-UVW S: Hong Liu, et al Expires March 2003 [Page 14] Internet-Draft EPP Over SOAP September 2002 S: S: S: S: If the client sends a SOAP message with session information that the server has knowledge of but is expired, the server will reject the SOAP message with an EPP response using the EPP result code 2200 "Authentication error", together with expired session information in the SOAP Header. S: S: S: S: S: ClientX S: NV0x12aNX3YTAsdK S: 1970-01-01T00:00:00.0Z S: S: S: S: S: S: S: S: Authentication error S: S: S: EFG-23456 S: 98765-UVW S: S: S: S: S: The client, on receipt of either response, should discontinue using the stale session information in future message exchanges with the server. NOTE 1: EPP currently does not have a result code for invalid Hong Liu, et al Expires March 2003 [Page 15] Internet-Draft EPP Over SOAP September 2002 session. It is an open issue whether result code 2200 is sufficient to convey the information to the client in the case of expired session. A new result code for "Expired/Non-existent session" is preferred. NOTE 2: It is also an open issue whether error also needs to be signaled to the client at the SOAP message level. 2.3 Message Processing Two types of EPP messages can be sent by an EPP client, i.e. EPP and EPP messages. Correspondingly, two types of EPP messages can be returned by an EPP server, i.e. EPP and EPP messages. Although SOAP supports a variety of messaging models and defines a message format for various message patterns, this memo will assume that a request/response process model MUST be followed for exchanging EPP messages via SOAP. After an EPP client send an EPP message via SOAP, the client MUST wait for a SOAP response from the EPP server before sending the next EPP message via SOAP. An EPP server MUST explicitly reject concurrent EPP messages from an EPP client after a session is successfully established. A non-well-formed XML message with SOAP Envelope sent by an EPP client or server MUST result in a SOAP Fault element for reporting errors specific to the SOAP protocol. A non-well-formed XML message or an invalid EPP message in the SOAP Body sent by an EPP client MUST result in an EPP response by the EPP server with a result code of 200x. A non-well-formed XML message or invalid XML message in the element in the SOAP Header sent by an EPP client MUST result in an EPP response by the EPP server with a result code of 2200. When an EPP client receives a non-well-formed XML message or invalid XML message in the element with SOAP Header sent by an EPP server, the client SHOULD abandon the current session and establish a new one, if the session identifier assigned by the server changes for every EPP message exchange. Please consult [2] for a discussion of other issues related to EPP message processing. Hong Liu, et al Expires March 2003 [Page 16] Internet-Draft EPP Over SOAP September 2002 2.4 Session Management An EPP client MUST issue an EPP command first before an EPP session is established. Before an EPP session is established via a valid EPP command, an EPP client MUST NOT send other EPP messages other than EPP and EPP . The maximum number of failed EPP commands can be sent is discussed in [2]. After an EPP session is established, all subsequent messages exchanged between an EPP client and an EPP server MUST contain an element in SOAP Header. An EPP server MAY extend the session expiration timestamp based on the activities of an EPP client. The EPP server MAY also change the session identifier as the session progresses for security reasons. The client MUST use the most current session identifier assigned by the server in any subsequent SOAP messages sent to the server (please refer to Section 2.2 for more details). An established EPP session can be terminated by an EPP client sending an EPP command to the server. The server will return an EPP response message with an expiration timestamp whose value is set as a past date in the element of in the SOAP Header. An established EPP session can be terminated by an EPP server implicitly if the server has decided that the session has been timeout based on the session expiration timestamp stored in the server. If an EPP client tries to use a session identifier that has been expired, the EPP server MUST reject explicitly the message sent by the client. NOTE: The original EPP result code 2501 in EPP-06 would be useful here. Hong Liu, et al Expires March 2003 [Page 17] Internet-Draft EPP Over SOAP September 2002 3. Formal Syntax The SOAP Header elements for EPP messages are specified in XML Schema [13, 14] notation. The formal syntax presented here is a complete schema representation of the SOAP Header elements suitable for automated validation of XML [12] instances. The BEGIN and END tags are not part of the schema; they are used to note the beginning and ending of the schema for URI registration purposes. BEGIN Extensible Provisioning Protocol v1.0 SOAP Header Schema. END Hong Liu, et al Expires March 2003 [Page 19] Internet-Draft EPP Over SOAP September 2002 4. Internationalization Considerations This memo introduces no international considerations beyond those introduced in [2]. 5. IANA Considerations This document uses URNs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [15]. If the ISEG approves this memo for publication, then two URI assignments will be requested. Registration request for the EPP over SOAP namespace: URI: urn:ietf:params:xml:ns:epp-soap-1.0 Registrant Contact: See the "Authors' Addresses" section of this document. XML: None. Namespace URIs do not represent an XML specification. Registration request for the EPP over SOAP XML schema: URI: urn:ietf:params:xml:schema:epp-soap-1.0 Registrant Contact: See the "Authors' Addresses" section of this document. XML: See the "Formal Syntax" section of this document. 6. Security Considerations SOAP, as the carrier of EPP messages, is simply another payload that can be distributed via another transport, such as HTTP, SMTP, BEEP, so the potential security vulnerabilities with EPP over SOAP are similar as with those underlying transport protocols. At minimum, transport layer security, such as TLS/SSL [16], MUST be provided for authentication and access control for EPP message exchanges via SOAP between an EPP client and an EPP server. Session identifiers embedded in the SOAP Header MUST be properly managed for every transaction after a successful EPP session establishment. Proper session timeout/expiration value MUST be maintained for avoiding potential security risks. Also, protection against denial of service attacks MUST be provided by network intrusion detection and load distribution systems. Please consult [2] for a discussion of EPP-specific security issues. Hong Liu, et al Expires March 2003 [Page 20] Internet-Draft EPP Over SOAP September 2002 7. Acknowledgements The authors gratefully acknowledges the helpful comments to this memo provided by various reviewers. 8. References [1] Bradner, S., "Key Words for Use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Hollenbeck, S., "Extensible Provisioning Protocol", Internet- Draft (work in progress), August, 2002. [3] Hollenbeck, S., "Extensible Provisioning Protocol Domain Mapping", Internet-Draft (work in progress), August, 2002. [4] Hollenbeck, S., "Extensible Provisioning Protocol Contact Mapping", Internet-Draft (work in progress), August, 2002. [5] Hollenbeck, S., "Extensible Provisioning Protocol Host Mapping", Internet-Draft (work in progress), August, 2002. [6] Hollenbeck, S., "Extensible Provisioning Protocol Transport over TCP", Internet-Draft (work in progress), August, 2002. [7] Gudgin, M., Hadley, M., Mendelsohn, N., Moreau, J., and H. Nielsen, "SOAP Version 1.2 Part 1: Messaging Framework", W3C Working Draft (work in progress), June 2002. [8] Gudgin, M., Hadley, M., Mendelsohn, N., Moreau, J., and H. Nielsen, "SOAP Version 1.2 Part 2: Adjuncts", W3C Working Draft (work in progress), June 2002. [9] Mountain, H.M., Kopecky, J., Williams, S., Daniels, G., and N. Mendelsohn, "SOAP Version 1.2 Email Binding", W3C Note (work in progress), June 2002. [10] O'Tuathail, E., and M. Rose, "Using the Simple Object Access Protocol (SOAP) in Blocks Extensible Exchange Protocol (BEEP)", RFC 3288, June 2002. Hong Liu, et al Expires March 2003 [Page 21] Internet-Draft EPP Over SOAP September 2002 [11] Baker, M., and M. Nottingham, "The application/soap+xml media type", Internet-Draft (work in progress), June 2002. [12] Bray, T., et al, "Extensible Markup Language (XML) 1.0 (Second Edition)", W3C Recommendation 6 , October 2000. [13] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML Schema Part 1: Structures", W3C Recommendation 2 , May 2001. [14] Biron, P., and A. Malhotra, "XML Schema Part 2: Datatypes", W3C Recommendation 2 , May 2001. [15] Mealling, M., "The IETF XML Registry", Internet-Draft, (work in progress), June 2002. [16] Dierks, T., and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. Hong Liu, et al Expires March 2003 [Page 22] Internet-Draft EPP Over SOAP September 2002 9. Authors' Addresses Hong Liu NeuStar, Inc Loudoun Tech Center 46000 Center Oak Plaza Sterling, VA 20166 U.S.A. Phone: +1-571-434-5400 Email: hong.liu@neustar.biz Ning Zhang NeuStar, Inc Loudoun Tech Center 45980 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. Phone: +1-571-434-5570 Email: tom.mcgarry@neustar.biz Richard Wilhelm NeuStar, Inc. Loudoun Tech Center 45980 Center Oak Plaza Sterling, VA 20166 U.S.A. Phone: +1-571-434-5515 Email: richard.wilhelm@neustar.biz Hong Liu, et al Expires March 2003 [Page 23] Internet-Draft EPP Over SOAP September 2002 A. Revisions From Previous Version None (initial draft). B. Full Copyright Statement Copyright (C) The Internet Society 2002. 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. Hong Liu, et al Expires March 2003 [Page 24]