diff options
Diffstat (limited to 'doc/rfc/rfc3735.txt')
| -rw-r--r-- | doc/rfc/rfc3735.txt | 731 |
1 files changed, 731 insertions, 0 deletions
diff --git a/doc/rfc/rfc3735.txt b/doc/rfc/rfc3735.txt new file mode 100644 index 0000000..2f0ecee --- /dev/null +++ b/doc/rfc/rfc3735.txt @@ -0,0 +1,731 @@ + + + + + + +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. + +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 Contents + + 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 + + + +Hollenbeck Informational [Page 1] + +RFC 3735 Guidelines for Extending the EPP March 2004 + + + 7.2. Informative References . . . . . . . . . . . . . . . . 11 + 8. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 9. Author's Address . . . . . . . . . . . . . . . . . . . . . . 12 + 10. Full Copyright Statement . . . . . . . . . . . . . . . . . . 13 + +1. 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 in RFC 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 in RFC 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 extended + + + +Hollenbeck 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 in RFC 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-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. + +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 2004 + + +2.2.2. Other Extensions + + URIs for extensions that are not intended for IETF standards track + use MUST conform to the URI syntax specifications described in RFC + 2396. + +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, 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. + + + +Hollenbeck Informational [Page 6] + +RFC 3735 Guidelines for Extending the EPP March 2004 + + +2.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 in section 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 in section + 2.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 in section 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 2004 + + +3. 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 section 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 + + + + + +Hollenbeck 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 observe + + + +Hollenbeck 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 in RFC 2277 [9]. + +5. IANA Considerations + + This memo has no direct impact on the IANA. Guidelines for + extensions that require IANA action are described in Section 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 in RFC 3552 [15]. + +7. References + +7.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)", RFC + 3730, 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", RFC + 2279, 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 2004 + + +9. Author's Address + + Scott Hollenbeck + VeriSign, Inc. + 21345 Ridgetop Circle + Dulles, VA 20166-6503 + USA + + EMail: shollenbeck@verisign.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hollenbeck Informational [Page 12] + +RFC 3735 Guidelines for Extending the EPP March 2004 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (2004). This document is subject + to the rights, licenses and restrictions contained in 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- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + +Hollenbeck Informational [Page 13] + |