Movatterモバイル変換

Network Working Group                                      S. HollenbeckRequest for Comments: 3735                                VeriSign, Inc.Category: Informational                                       March 2004Guidelines 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.Abstract   The 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.Table of Contents1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . .21.1.  Conventions Used In This Document. . . . . . . . . . .22.  Principles of Protocol Extension . . . . . . . . . . . . . .32.1.  Documenting Extensions . . . . . . . . . . . . . . . .32.2.  Identifying Extensions . . . . . . . . . . . . . . . .42.2.1.  Standards Track Extensions . . . . . . . . . .42.2.2.  Other Extensions . . . . . . . . . . . . . . .52.3.  Extension Announcement and Selection . . . . . . . . .52.4.  Protocol-level Extension . . . . . . . . . . . . . . .72.5.  Object-level Extension . . . . . . . . . . . . . . . .72.6.  Command-Response Extension . . . . . . . . . . . . . .72.7.  Authentication Information Extension . . . . . . . . .73.  Selecting an Extension Mechanism . . . . . . . . . . . . . .83.1.   Mapping and Extension Archives  . . . . . . . . . . .94.  Internationalization Considerations  . . . . . . . . . . . .95.  IANA Considerations  . . . . . . . . . . . . . . . . . . . .106.  Security Considerations  . . . . . . . . . . . . . . . . . .107.  References . . . . . . . . . . . . . . . . . . . . . . . . .107.1.  Normative References . . . . . . . . . . . . . . . . .10Hollenbeck                   Informational                      [Page 1]

RFC 3735            Guidelines for Extending the EPP          March 20047.2.  Informative References . . . . . . . . . . . . . . . .118.  URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . .119.  Author's Address . . . . . . . . . . . . . . . . . . . . . .1210. Full Copyright Statement . . . . . . . . . . . . . . . . . .131. Introduction   The Extensible Provisioning Protocol (EPP, [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, [3]), and      is specified in XML Schema ([4] and [5]) with XML namespaces [6]      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      [10] (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.1.1.  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 inRFC 2119 [1].Hollenbeck                   Informational                      [Page 2]

RFC 3735            Guidelines for Extending the EPP          March 2004   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.2.  Principles of Protocol Extension   The EPP extension model is based on the XML representation for a   wildcard schema component using an <any> element information item (as   described in section 3.10.2 of [4]) and XML namespaces [6].  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 inRFC 3470 [11].   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.1.  Documenting Extensions   The EPP core specification [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 extendedHollenbeck                   Informational                      [Page 3]

RFC 3735            Guidelines for Extending the EPP          March 2004   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.2.2.  Identifying Extensions   An EPP extension is uniquely identified by a Uniform Resource   Identifier (URI, defined inRFC 2396 [7]).  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-ext1http://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.2.2.1.  Standards Track Extensions   URIs for extensions intended for IETF standards track use MUST   conform to the URN syntax specifications and registration procedures   described in [8].Hollenbeck                   Informational                      [Page 4]

RFC 3735            Guidelines for Extending the EPP          March 20042.2.2.  Other Extensions   URIs for extensions that are not intended for IETF standards track   use MUST conform to the URI syntax specifications described inRFC2396.2.3.  Extension Announcement and Selection   An EPP server MUST announce extensions that are available for client   use as part of a <greeting> element that is sent to a client before   the client establishes an interactive session with the server.  The   <greeting> element contains zero or more <svcExtension> elements   that, if present, contain a URI identifying an available extension:   S:<?xml version="1.0" encoding="UTF-8" standalone="no"?>   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:  <greeting>   S:    <svID>Example EPP server epp.example.com</svID>   S:    <svDate>2000-06-08T22: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>urn:ietf:params:xml:ns:foo-ext1</extURI>   S:        <extURI>http://custom/obj1ext-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>   In the example above, the server is announcing the availability of   two extensions:Hollenbeck                   Informational                      [Page 5]

RFC 3735            Guidelines for Extending the EPP          March 2004      urn:ietf:params:xml:ns:foo-ext1, andhttp://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 thehttp://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.Hollenbeck                   Informational                      [Page 6]

RFC 3735            Guidelines for Extending the EPP          March 20042.4.  Protocol-level Extension   EPP defines a set of structures for client-server command-response   interaction, but additional structures MAY be added to the protocol.   New structure definition is a matter of defining a schema for the   structures that defines needed functionality and assigning a URI to   uniquely identify the object namespace and schema.  Specific   protocol-level extension mechanisms are described insection 2.7.1 of   the EPP core protocol specification [2].2.5.  Object-level Extension   EPP commands and responses do not contain attributes that are   specific to any managed object.  Every command and response MUST   contain elements bound to an object namespace.  Object definition is   a matter of defining a schema for the object that defines   functionality for each needed command and associated response, and   assigning a URI to uniquely identify the object namespace and schema.   Specific object-level extension mechanisms are described insection2.7.2 of the EPP core protocol specification [2].2.6.  Command-Response Extension   EPP command and response structures defined in existing object   mappings MAY also be extended.  For example, an object mapping that   describes general functionality for the provisioning of Internet   domain names can be extended to included additional command and   response elements needed for the provisioning of domain names that   represent E.164 telephone numbers [12].  Specific command-response   extension mechanisms are described insection 2.7.3 of the EPP core   protocol specification [2].2.7.  Authentication Information Extension   Some EPP object mappings, such as the Internet domain name mapping   [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 ([4] and [5]), this can be accomplished by offering an element   choice that includes an <any> element information item:      <any namespace="##other"/>Hollenbeck                   Informational                      [Page 7]

RFC 3735            Guidelines for Extending the EPP          March 20043.  Selecting an Extension Mechanism   Extensibility is a powerful feature of XML, but it also provides   multiple opportunities to make poor design decisions.  There are   typically several different ways to accomplish a single task, and   while all may "work" (for some definition of "work") one extension   form will usually be more appropriate than others to complete a given   task.  The following sequence of steps can be followed to select an   appropriate extension form to solve an extension problem:   o  Command-Response Extension: Adding elements to an existing object      mapping is the simplest form of extension available, and is thus      the form that should be explored before any other form is      considered.  The first question to ask when considering an      extension form is thus:         Can the task be accomplished by adding to an existing object         mapping or changing an existing object mapping slightly?      If the answer to this question is "yes", you should consider      extending an existing object mapping to complete your task.      Knowing where to find object mappings is critical to being able to      answer this question; see sectionSection 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, considerHollenbeck                   Informational                      [Page 8]

RFC 3735            Guidelines for Extending the EPP          March 2004      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.3.1.  Mapping and Extension Archives   Existing object mappings are a critical resource when trying to   select an appropriate extension form.  Existing mappings or   extensions can provide a solid basis for further extension, but   designers have to know where to find them to consider them for use.   Several organizations maintain archives of XML structures that can be   useful extension platforms.  These include:   o  The IETF: Object mappings and other extensions have been      documented in RFCs and Internet-Drafts.   o  IANA: Guidelines and registration procedures for an IANA XML      registry used by the IETF are described in "The IETF XML Registry"      [8].   o  OASIS [16]: OASIS maintains an XML archive containing schema      definitions for use in the business applications of XML.   o  XML.org [17]: 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.4.  Internationalization Considerations   EPP is represented in XML [3], which requires conforming parsers to   recognize both UTF-8 [13] and UTF-16 [14]; support for other   character encodings is also possible.  EPP extensions MUST observeHollenbeck                   Informational                      [Page 9]

RFC 3735            Guidelines for Extending the EPP          March 2004   both the Internationalization Considerations described in the EPP   core protocol specification [2] and IETF policy on the use of   character sets and languages described inRFC 2277 [9].5.  IANA Considerations   This memo has no direct impact on the IANA.  Guidelines for   extensions that require IANA action are described inSection 2.2.1.6. Security Considerations   EPP extensions inherit the security services of the protocol   structure that's being extended.  For example, an extension of an   object mapping inherits all of the security services of the object   mapping.  Extensions MAY specify additional security services, such   as services for peer entity authentication, confidentiality, data   integrity, authorization, access control, or non-repudiation.   Extensions MUST NOT mandate removal of security services available in   the protocol structure being extended.   Protocol designers developing EPP extensions need to be aware of the   security threats to be faced in their intended operating environment   so that appropriate security services can be provided.  Guidelines   for designers to consider and suggestions for writing an appropriate   Security Considerations section can be found inRFC 3552 [15].7.  References7.1.  Normative 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 (EPP)",RFC3730, March 2004.   [3]  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>.   [4]  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/>.   [5]  Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes", W3C        REC-xmlschema-2, May 2001, <http://www.w3.org/TR/xmlschema-2/>.Hollenbeck                   Informational                     [Page 10]

RFC 3735            Guidelines for Extending the EPP          March 2004   [6]  Bray, T., Hollander, D. and A. Layman, "Namespaces in XML", W3C        REC-xml-names, January 1999, <http://www.w3.org/TR/REC-xml-names>.   [7]  Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource        Identifiers (URI): Generic Syntax",RFC 2396, August 1998.   [8]  Mealling, M., "The IETF XML Registry",BCP 81,RFC 3688, January        2004.   [9]  Alvestrand, H., "IETF Policy on Character Sets and Languages",BCP 18,RFC 2277, January 1998.7.2.  Informative References   [10] Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Domain        Name Mapping",RFC 3731, March 2004.   [11] 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.   [12] Hollenbeck, S., "Extensible Provisioning Protocol E.164 Number        Mapping", Work in Progress, February 2003.   [13] Yergeau, F., "UTF-8, a transformation format of ISO 10646",RFC2279, January 1998.   [14] Hoffman, P. and F. Yergeau, "UTF-16, an encoding of ISO 10646",RFC 2781, February 2000.   [15] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on        Security Considerations",BCP 72,RFC 3552, July 2003.8.  URIs   [16]  <http://oasis-open.org/>   [17]  <http://xml.org/>Hollenbeck                   Informational                     [Page 11]

RFC 3735            Guidelines for Extending the EPP          March 20049.  Author's Address   Scott Hollenbeck   VeriSign, Inc.   21345 Ridgetop Circle   Dulles, VA  20166-6503   USA   EMail: shollenbeck@verisign.comHollenbeck                   Informational                     [Page 12]

RFC 3735            Guidelines for Extending the EPP          March 200410.  Full Copyright Statement   Copyright (C) The Internet Society (2004).  This document is subject   to the rights, licenses and restrictions contained inBCP 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 inBCP 78 andBCP 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 athttp://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-   ipr@ietf.org.Acknowledgement   Funding for the RFC Editor function is currently provided by the   Internet Society.Hollenbeck                   Informational                     [Page 13]