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
<draft-liu-epp-soap-00.txt>
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 <majordomo@cafax.se> 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 <login> command, the SOAP
Header MUST contain an <epp-soap:session> element for each message
exchanged subsequently, including in the first EPP response to a
successful EPP <login> command. The <epp-soap:session> element MUST
contain a "mustUnderstand" attribute with value "true".
An <epp-soap:session> element contains the following child elements:
- A <clID> element that contains the client identifier used for
establishing the EPP session via an EPP <login> command.
- A <sessionID> 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 <newSessionID> 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 <sessionID>, 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 <exDate> 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 <hello> message.
C:<?xml version="1.0" encoding="UTF-8"?>
C:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
C: <env:Header/>
C: <env:Body>
C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
C: epp-1.0.xsd">
C: <!-- EPP <hello> message sent by the client
C: for session setup -->
C: <hello/>
C: </epp>
C: </env:Body>
C:</env:Envelope>
Note that a SOAP message enclosing an EPP <hello> message in the SOAP
Body but without the <epp-soap:session> 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 <hello> message
sent by the client after the session is established, where the SOAP
Header contains the session information <epp-soap:session> element
(see below).
(2) The server responds to the client with the EPP <greeting>
message, listing the object mappings and options it supports for the
session.
S:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
Hong Liu, et al Expires March 2003 [Page 6]
Internet-Draft EPP Over SOAP September 2002
S: <env:Header/>
S: <env:Body>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP <greeting> message returned by the server
for session setup -->
S: <greeting>
S: <svID>Example EPP server epp.example.tld</svID>
S: <svDate>2002-09-27T22:00:00.0Z</svDate>
S: <svcMenu>
S: <version>1.0</version>
S: <lang>en</lang>
S: <lang>fr</lang>
S: <objURI>urn:ietf:params:xml:ns:obj1</objURI>
S: <objURI>urn:ietf:params:xml:ns:obj2</objURI>
S: <objURI>urn:ietf:params:xml:ns:obj3</objURI>
S: <svcExtension>
S: <extURI>http://custom/obj1ext-1.0</extURI>
S: <extURI>http://custom/obj2ext-1.0</extURI>
S: </svcExtension>
S: </svcMenu>
S: <dcp>
S: <access><all/></access>
S: <statement>
S: <purpose><admin/><prov/></purpose>
S: <recipient><ours/><public/></recipient>
S: <retention><stated/></retention>
S: </statement>
S: </dcp>
S: </greeting>
S: </epp>
S: </env:Body>
S:</env:Envelope>
Note that the <greeting> 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 <login> command.
C:<?xml version="1.0" encoding="UTF-8"?>
C:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
C: <env:Header/>
C: <env:Body>
Hong Liu, et al Expires March 2003 [Page 7]
Internet-Draft EPP Over SOAP September 2002
C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
C: epp-1.0.xsd">
S: <!-- EPP <login> command sent by the client -->
C: <command>
C: <login>
C: <clID>ClientX</clID>
C: <pw>foo-BAR2</pw>
C: <newPW>bar-FOO2</newPW>
C: <options>
C: <version>1.0</version>
C: <lang>en</lang>
C: </options>
C: <svcs>
C: <objURI>urn:ietf:params:xml:ns:obj1</objURI>
C: <objURI>urn:ietf:params:xml:ns:obj2</objURI>
C: <svcExtension>
C: <extURI>http://custom/obj1ext-1.0</extURI>
C: </svcExtension>
C: </svcs>
C: </login>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C: </epp>
C: </env:Body>
C:</env:Envelope>
(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:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
S: <env:Header>
S: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
S: epp-soap-1.0.xsd" env:mustUnderstand="true">
S: <exp-soap:clID>ClientX</clID>
S: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
Hong Liu, et al Expires March 2003 [Page 8]
Internet-Draft EPP Over SOAP September 2002
S: <exp-soap:exDate>2002-09-30T23:59:59.0Z</exp-soap:exDate>
S: </epp-soap:session>
S: </env:Header>
S: <env:Body>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP <login> response returned by the server -->
S: <response>
S: <result code="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>
S: <svTRID>
S: </trID>
S: </response>
S: </epp>
S: </env:Body>
S:</env:Envelope>
(5) At the receipt of the <login> 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 <check>
command for a few domains to the server, the SOAP message looks like
the following:
C:<?xml version="1.0" encoding="UTF-8"?>
C:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
C: <env:Header>
C: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
C: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
C: epp-soap-1.0.xsd" env:mustUnderstand="true">
C: <exp-soap:clID>ClientX</clID>
C: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
C: </epp-soap:session>
C: </env:Header>
C: <env:Body>
C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
Hong Liu, et al Expires March 2003 [Page 9]
Internet-Draft EPP Over SOAP September 2002
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
C: epp-1.0.xsd">
S: <!-- EPP <domain:check> command sent by the client -->
C: <command>
C: <check>
C: <domain:check
C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:domain-1.0
C: domain-1.0.xsd">
C: <domain:name>example1.tld</domain:name>
C: <domain:name>example2.tld</domain:name>
C: <domain:name>example3.tld</domain:name>
C: </domain:check>
C: </check>
C: <clTRID>ABC-12345</clTRID>
C: </command>
C: </epp>
C: </env:Body>
C:</env:Envelope>
The SOAP message for the server response to the <check> command looks
like the following:
S:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
S: <env:Header>
S: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
S: epp-soap-1.0.xsd" env:mustUnderstand="true">
S: <exp-soap:clID>ClientX</clID>
S: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
S: <exp-soap:exDate>2002-09-30T23:59:59.0Z</exp-soap:exDate>
S: </epp-soap:session>
S: </env:Header>
S: <env:Body>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP <domain:check> response returned by the server -->
S: <response>
S: <result code="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <resData>
Hong Liu, et al Expires March 2003 [Page 10]
Internet-Draft EPP Over SOAP September 2002
S: <domain:chkData
S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:domain-1.0
S: domain-1.0.xsd">
S: <domain:cd>
S: <domain:name avail="1">example1.tld</domain:name>
S: </domain:cd>
S: <domain:cd>
S: <domain:name avail="0">example1.tld</domain:name>
S: <domain:reason>In use</domain:reason>
S: </domain:cd>
S: <domain:cd>
S: <domain:name avail="1">example3.tld</domain:name>
S: </domain:cd>
S: </domain:chkData>
S: </resData>
S: <trID>
S: <clTRID>ABC-12345</clTRID>
S: <svTRID>54322-XYZ</svTRID>
S: </trID>
S: </response>
S: </epp>
S: </env:Body>
S:</env:Envelope>
A noted earlier, any <hello> message sent by the client after the
session is set up should carry the session information.
C:<?xml version="1.0" encoding="UTF-8"?>
C:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
C: <env:Header>
C: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
C: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
C: epp-soap-1.0.xsd" env:mustUnderstand="true">
C: <exp-soap:clID>ClientX</clID>
C: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
C: <env:Body>
C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
C: epp-1.0.xsd">
C: <!-- EPP <hello> message sent by the client
C: during a session -->
C: <hello/>
C: <clTRID>BCD-23456</clTRID>
C: </epp>
Hong Liu, et al Expires March 2003 [Page 11]
Internet-Draft EPP Over SOAP September 2002
C: </env:Body>
C:</env:Envelope>
The <greeting> message returned by the server during the session
should also carry the session information.
S:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
S: <env:Header>
S: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
S: epp-soap-1.0.xsd" env:mustUnderstand="true">
S: <exp-soap:clID>ClientX</clID>
S: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
S: <exp-soap:exDate>2002-09-30T23:59:59.0Z</exp-soap:exDate>
S: </epp-soap:session>
S: </env:Header>
S: <env:Body>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP <greeting> message returned by the server
S: during a session -->
S: <greeting>
S: <svID>Example EPP server epp.example.tld</svID>
S: <svDate>2002-09-28T18:30:29.0Z</svDate>
S: <svcMenu>
S: <version>1.0</version>
S: <lang>en</lang>
S: <lang>fr</lang>
S: <objURI>urn:ietf:params:xml:ns:obj1</objURI>
S: <objURI>urn:ietf:params:xml:ns:obj2</objURI>
S: <objURI>urn:ietf:params:xml:ns:obj3</objURI>
S: <svcExtension>
S: <extURI>http://custom/obj1ext-1.0</extURI>
S: <extURI>http://custom/obj2ext-1.0</extURI>
S: </svcExtension>
S: </svcMenu>
S: <dcp>
S: <access><all/></access>
S: <statement>
S: <purpose><admin/><prov/></purpose>
S: <recipient><ours/><public/></recipient>
S: <retention><stated/></retention>
S: </statement>
Hong Liu, et al Expires March 2003 [Page 12]
Internet-Draft EPP Over SOAP September 2002
S: </dcp>
S: </greeting>
S: </epp>
S: </env:Body>
S:</env:Envelope>
(6) At some point before the session expires, the client may choose
to close the session by sending the server an EPP <logout> command:
C:<?xml version="1.0" encoding="UTF-8"?>
C:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
C: <env:Header>
C: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
C: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
C: epp-soap-1.0.xsd" env:mustUnderstand="true">
C: <exp-soap:clID>ClientX</clID>
C: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
C: <env:Body>
C: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
C: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
C: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
C: epp-1.0.xsd">
C: <!-- EPP <logout> message sent by the client
C: to end the session -->
C: <logout/>
C: <clTRID>CDE-34567</clTRID>
C: </epp>
C: </env:Body>
C:</env:Envelope>
The server responds to the client to terminate the session.
S:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
S: <env:Header>
S: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
S: epp-soap-1.0.xsd" env:mustUnderstand="true">
S: <exp-soap:clID>ClientX</clID>
S: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
S: <exp-soap:exDate>1970-01-01T00:00:00.0Z</exp-soap:exDate>
S: </epp-soap:session>
S: </env:Header>
S: <env:Body>
Hong Liu, et al Expires March 2003 [Page 13]
Internet-Draft EPP Over SOAP September 2002
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP response to the <logout> command -->
S: <response>
S: <result code="1000">
S: <msg>Command completed successfully</msg>
S: </result>
S: <trID>
S: <clTRID>CDE-34567</clTRID>
S: <svTRID>76543-OPQ</svTRID>
S: </trID>
S: </response>
S: </epp>
S: </env:Body>
S:</env:Envelope>
Note that the <exDate> child element of <epp-soap:session> 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:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
S: <env:Header/>
S: <env:Body>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP server response to stale session command -->
S: <response>
S: <result code="2200">
S: <msg>Authentication error</msg>
S: </result>
S: <trID>
S: <clTRID>EFG-23456</clTRID>
S: <svTRID>98765-UVW</svTRID>
S: </trID>
Hong Liu, et al Expires March 2003 [Page 14]
Internet-Draft EPP Over SOAP September 2002
S: </response>
S: </epp>
S: </env:Body>
S:</env:Envelope>
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:<?xml version="1.0" encoding="UTF-8"?>
S:<env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">
S: <env:Header>
S: <epp-soap:session xmlns="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:epp-soap="urn:ietf:params:xml:ns:epp-soap-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-soap-1.0
S: epp-soap-1.0.xsd" env:mustUnderstand="true">
S: <exp-soap:clID>ClientX</clID>
S: <exp-soap:sessionID>NV0x12aNX3YTAsdK</exp-soap:sessionID>
S: <exp-soap:exDate>1970-01-01T00:00:00.0Z</exp-soap:exDate>
S: </epp-soap:session>
S: </env:Header>
S: <env:Body>
S: <epp xmlns="urn:ietf:params:xml:ns:epp-1.0"
S: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
S: xsi:schemaLocation="urn:ietf:params:xml:ns:epp-1.0
S: epp-1.0.xsd">
S: <!-- EPP server response to stale session command -->
S: <response>
S: <result code="2200">
S: <msg>Authentication error</msg>
S: </result>
S: <trID>
S: <clTRID>EFG-23456</clTRID>
S: <svTRID>98765-UVW</svTRID>
S: </trID>
S: </response>
S: </epp>
S: </env:Body>
S:</env:Envelope>
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
<hello> and EPP <command> messages. Correspondingly, two types of EPP
messages can be returned by an EPP server, i.e. EPP <greeting> and
EPP <response> 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 <epp-
soap:session> 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 <epp-soap:session> 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 <hello> command first before an EPP
session is established.
Before an EPP session is established via a valid EPP <login> command,
an EPP client MUST NOT send other EPP messages other than EPP <hello>
and EPP <login>. The maximum number of failed EPP <login> 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
<epp-soap:session> 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 <logout> command to the server. The server will return an EPP
<logout> response message with an expiration timestamp whose value is
set as a past date in the <exDate> element of <epp-soap:session> 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
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="urn:iana:xml:ns:epp-soap-1.0"
xmlns:epp-soap="urn:iana:xml:ns:epp-soap-1.0"
xmlns:epp="urn:iana:xml:ns:epp-1.0"
xmlns:eppcom="urn:iana:xml:ns:eppcom-1.0"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<!--
Import common element types.
-->
<import namespace="urn:iana:xml:ns:eppcom-1.0"
schemaLocation="eppcom-1.0.xsd"/>
<import namespace="urn:iana:xml:ns:epp-1.0"
schemaLocation="epp-1.0.xsd"/>
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0
SOAP Header Schema.
</documentation>
</annotation>
<!--
Child elements found in SOAP header.
-->
<element name="session" type="epp-soap:sessionType"/>
<!--
Child elements of "sessionType"
-->
<complexType name="sessionType">
<sequence>
<element name="clID" type="eppcom:clIDType"/>
<element name="sessionID" type="epp-soap:sessionIDType"/>
<element name="newSessionID" type="epp-soap:sessionIDType"
minOccurs="0"/>
<element name="exDate" type="dateTime" minOccurs="0"/>
</sequence>
</complexType>
<!--
Hong Liu, et al Expires March 2003 [Page 18]
Internet-Draft EPP Over SOAP September 2002
Session IDs are strings with minimum length restrictions.
-->
<simpleType name="sessionIDType">
<restriction base="normalizedString">
<minLength value="8"/>
</restriction>
</simpleType>
<!--
End of schema.
-->
</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 <draft-ietf-provreg-epp-07.txt> (work in progress),
August, 2002.
[3] Hollenbeck, S., "Extensible Provisioning Protocol Domain
Mapping", Internet-Draft <draft-ietf-provreg-epp-domain-05.txt>
(work in progress), August, 2002.
[4] Hollenbeck, S., "Extensible Provisioning Protocol Contact
Mapping", Internet-Draft <draft-ietf-provreg-epp-contact-05.txt>
(work in progress), August, 2002.
[5] Hollenbeck, S., "Extensible Provisioning Protocol Host Mapping",
Internet-Draft <draft-ietf-provreg-epp-host-05.txt> (work in
progress), August, 2002.
[6] Hollenbeck, S., "Extensible Provisioning Protocol Transport over
TCP", Internet-Draft <draft-ietf-provreg-epp-tcp-05.txt> (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 <http://www.w3.org/TR/soap12-part1> (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
<http://www.w3.org/TR/soap12-part2> (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
<http://www.w3.org/TR/soap12-email> (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 <draft-baker-soap-media-reg-01.txt> (work
in progress), June 2002.
[12] Bray, T., et al, "Extensible Markup Language (XML) 1.0 (Second
Edition)", W3C Recommendation 6 <http://www.w3.org/TR/REC-xml>,
October 2000.
[13] Thompson, H., Beech, D., Maloney, M., and N. Mendelsohn, "XML
Schema Part 1: Structures", W3C Recommendation 2
<http://www.w3.org/TR/xmlschema-1/>, May 2001.
[14] Biron, P., and A. Malhotra, "XML Schema Part 2: Datatypes", W3C
Recommendation 2 <http://www.w3.org/TR/xmlschema-2/>, May 2001.
[15] Mealling, M., "The IETF XML Registry", Internet-Draft, <draft-
mealling-iana-xmlns-registry-04> (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]