Network Working Group S. Hollenbeck Request for Comments: 3735 VeriSign, Inc. Category: Informational March 2004 Guidelines for Extending the Extensible Provisioning Protocol (EPP) Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2004). All Rights Reserved.
AbstractThe Extensible Provisioning Protocol (EPP) is an application layer client-server protocol for the provisioning and management of objects stored in a shared central repository. Specified in XML, the protocol defines generic object management operations and an extensible framework that maps protocol operations to objects. This document presents guidelines for use of EPP's extension mechanisms to define new features and object management capabilities. 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Conventions Used In This Document. . . . . . . . . . . 2 2. Principles of Protocol Extension . . . . . . . . . . . . . . 3 2.1. Documenting Extensions . . . . . . . . . . . . . . . . 3 2.2. Identifying Extensions . . . . . . . . . . . . . . . . 4 2.2.1. Standards Track Extensions . . . . . . . . . . 4 2.2.2. Other Extensions . . . . . . . . . . . . . . . 5 2.3. Extension Announcement and Selection . . . . . . . . . 5 2.4. Protocol-level Extension . . . . . . . . . . . . . . . 7 2.5. Object-level Extension . . . . . . . . . . . . . . . . 7 2.6. Command-Response Extension . . . . . . . . . . . . . . 7 2.7. Authentication Information Extension . . . . . . . . . 7 3. Selecting an Extension Mechanism . . . . . . . . . . . . . . 8 3.1. Mapping and Extension Archives . . . . . . . . . . . 9 4. Internationalization Considerations . . . . . . . . . . . . 9 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . 10 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 7.1. Normative References . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . 11 8. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 9. Author's Address . . . . . . . . . . . . . . . . . . . . . . 12 10. Full Copyright Statement . . . . . . . . . . . . . . . . . . 13 2]) was originally designed to provide a standard Internet domain name registration protocol for use between Internet domain name registrars and domain name registries. However, specific design decisions were made to ensure that the protocol could also be used in other provisioning environments. Specifically: o Extensibility has been a design goal from the very beginning. EPP is represented in the Extensible Markup Language (XML, ), and is specified in XML Schema ( and ) with XML namespaces  used to identify protocol grammars. o The EPP core protocol specification describes general protocol functions, not objects to be managed by the protocol. Managed object definitions, such as the mapping for Internet domain names  (itself a protocol extension), are loosely coupled to the core specification. o A concentrated effort was made to separate required minimum protocol functionality from object management operating logic. o Several extension mechanisms were included to allow designers to add new features or to customize existing features for different operating environments. This document describes EPP's extensibility features in detail and provides guidelines for their use. Though written specifically for protocol designers considering EPP as the solution to a provisioning problem, anyone interested in using XML to represent IETF protocols might find these guidelines useful. XML is case sensitive. Unless stated otherwise, XML instances and examples provided in this document MUST be interpreted in the character case presented to develop a conforming implementation. RFC 2119 .
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 illustrate element relationships and is not a REQUIRED feature of this specification. section 3.10.2 of ) and XML namespaces . This section provides guidelines for the development of protocol extensions and describes the extension model in detail. Extending a protocol implies the addition of features without changing the protocol itself. In EPP that means that an extension MUST NOT alter an existing protocol schema as changes may result in new versions of an existing schema, not extensions of an existing schema. For example, a designer MUST NOT add new elements to an existing schema and call the result an "extension" of the protocol. The result is a new, non-backwards-compatible version of an existing schema. Extensions MUST adhere to the principles described in this section to be considered valid protocol extensions. EPP extensions MUST be specified in XML. This ensures that parsers capable of processing EPP structures will also be capable of processing EPP extensions. Guidelines for the use of XML in IETF protocols (thus good information for extension designers) can be found in RFC 3470 . A designer MUST remember that extensions themselves MAY also be extensible. A good chain of extensions is one in which the protocol schemas evolve from general functionality to more specific (perhaps even more limited) functionality. 2] has an appendix that contains a suggested outline to document protocol extensions. Designers are free to use this template or any other format as they see fit, but the extension document SHOULD at a minimum address all of the topics listed in the template. Extension designers need to consider the intended audience and consumers of their extensions. Extensions MAY be documented as Internet-Draft and RFC documents if the designer is facing requirements for coordination, interoperability, and broad distribution, though the intended maturity level (informational, proposed standard, etc.) largely depends on what is being extended
and the amount of general interest in the extension. An extension to a standards-track specification with broad interest might well be a candidate for standards track publication, whereas an extension to a standards track specification with limited interest might be better suited for informational publication. Extensions need not be published as Internet-Draft or RFC documents if they are intended for operation in a closed environment or are otherwise intended for a limited audience. In such cases extensions MAY be documented in a file and structural format that is appropriate for the intended audience. RFC 2396 ). The URI used to identify the extension MUST also be used to identify the XML namespace associated with the extension. Any valid URI MAY be used to identify an EPP extension, though the selection of a URI form (Uniform Resource Locator (URL) vs. Uniform Resource Name (URN), hierarchical vs. relative, etc.) SHOULD depend on factors such as organizational policies on change control and a balance between locating resources and requirements for persistence. An extension namespace MAY describe multiple extension mechanisms, such as definition of new protocol features, objects, or elements, within the schema used to define the namespace. The following are sample extension-identifying URIs: urn:ietf:params:xml:ns:foo-ext1 http://custom/obj1ext-1.0 Extension designers MAY include version information in the URI used to identify an extension. If version information is included in the URI, the URI itself will need to change as the extension is revised or updated. 8].
urn:ietf:params:xml:ns:foo-ext1, and http://custom/obj1ext-1.0 An EPP client MUST establish a session with an EPP server using the EPP <login> command before attempting to use any standard commands or extensions. The <login> command contains zero or more <svcExtension> elements that, if present, contain a URI identifying an available extension that the client wishes to use during the course of the session: C:<?xml version="1.0" encoding="UTF-8" standalone="no"?> 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: <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: <objURI>urn:ietf:params:xml:ns:obj3</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> In the example above, the client indicates that it wishes to use an extension identified by the http://custom/obj1ext-1.0 URI during the session established upon successful completion of the <login> command. An EPP server MUST announce all extensions that are publicly available for client use. An EPP client MUST NOT request an extension that has not been announced by the server. An EPP server MAY restrict a client's ability to select an extension based on a client's identity and authorizations granted by the server operator.
section 2.7.1 of the EPP core protocol specification . section 2.7.2 of the EPP core protocol specification . 12]. Specific command-response extension mechanisms are described in section 2.7.3 of the EPP core protocol specification . 10], include elements to associate authentication information (such as a password) with an object. The schema for any object mapping that supports authentication information SHOULD be flexible enough to specify multiple forms of authentication information. With XML Schema ( and ), this can be accomplished by offering an element choice that includes an <any> element information item: <any namespace="##other"/>
Section 3.1 for information describing mapping archives. If the answer to this question is "no", consider an object-level extension next. o Object-level Extension: If there is no existing object mapping that can be extended to meet your requirements, consider developing a new object mapping. The second question to ask when considering an extension form is thus: Can the task be accomplished using the existing EPP command and response structures applied to a new object? If the answer to this question is "yes", you should consider developing a new object mapping to complete your task. A new object mapping should differ significantly from existing object mappings; if you find that a new mapping is replicating a significant number of structures found in an existing mapping you probably answered the command-response question incorrectly. If the answer to this question is "no", consider a protocol-level extension next. o Protocol-level Extension: If there is no existing object mapping that can be extended to meet your requirements and the existing EPP command and response structures are insufficient, consider
developing new protocol commands, responses, or other structures. The third and final question to ask when considering an extension form is thus: Can the task be accomplished by adding new EPP commands, responses, or other structures applied to new or existing objects? If the answer to this question is "no", EPP can not be used directly to complete your task. If the answer to this question is "yes", extend the protocol by defining new operational structures. The extension forms and decision points listed here are presented in order of complexity. Selecting an extension form without careful consideration of the available extension options can add complexity without any gain in functionality. 8]. o OASIS : OASIS maintains an XML archive containing schema definitions for use in the business applications of XML. o XML.org : XML.org maintains an XML archive containing schema definitions for use in multiple industries. o Other archives are likely in the future. Consult your favorite Internet search engine for additional resources. 3], which requires conforming parsers to recognize both UTF-8  and UTF-16 ; support for other character encodings is also possible. EPP extensions MUST observe
both the Internationalization Considerations described in the EPP core protocol specification  and IETF policy on the use of character sets and languages described in RFC 2277 . Section 2.2.1. RFC 3552 .  Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.  Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", RFC 3730, March 2004.  Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-xml, October 2000, <http://www.w3.org/TR/REC-xml>.  Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML Schema Part 1: Structures", W3C REC-xmlschema-1, May 2001, <http://www.w3.org/TR/xmlschema-1/>.  Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes", W3C REC-xmlschema-2, May 2001, <http://www.w3.org/TR/xmlschema-2/>.
 Bray, T., Hollander, D. and A. Layman, "Namespaces in XML", W3C REC-xml-names, January 1999, <http://www.w3.org/TR/REC-xml- names>.  Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, August 1998.  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.  Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998.  Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Domain Name Mapping", RFC 3731, March 2004.  Hollenbeck, S., Rose, M. and L. Masinter, "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols", BCP 70, RFC 3470, January 2003.  Hollenbeck, S., "Extensible Provisioning Protocol E.164 Number Mapping", Work in Progress, February 2003.  Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 2279, January 1998.  Hoffman, P. and F. Yergeau, "UTF-16, an encoding of ISO 10646", RFC 2781, February 2000.  Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, July 2003. http://oasis-open.org/>  <http://xml.org/>
BCP 78 and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf- email@example.com. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.