Network Working Group S. Hollenbeck Internet-Draft VeriSign, Inc. Expires: April 21, 2003 October 21, 2002 Guidelines for Extending the Extensible Provisioning Protocol draft-ietf-provreg-epp-ext-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. This Internet-Draft will expire on April 21, 2003. Copyright Notice Copyright (C) The Internet Society (2002). 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. Conventions Used In This Document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this Hollenbeck Expires April 21, 2003 [Page 1] Internet-Draft Extending EPP October 2002 document are to be interpreted as described in RFC 2119 [1]. 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Changes from Previous Version . . . . . . . . . . . . . . . 3 2. Principles of Protocol Extension . . . . . . . . . . . . . . 4 2.1 Documenting Extensions . . . . . . . . . . . . . . . . . . . 4 2.2 Identifying Extensions . . . . . . . . . . . . . . . . . . . 5 2.2.1 Standards Track Extensions . . . . . . . . . . . . . . . . . 5 2.2.2 Other Extensions . . . . . . . . . . . . . . . . . . . . . . 5 2.3 Extension Announcement and Selection . . . . . . . . . . . . 5 2.4 Protocol-level Extension . . . . . . . . . . . . . . . . . . 7 2.5 Object-level Extension . . . . . . . . . . . . . . . . . . . 8 2.6 Command-Response Extension . . . . . . . . . . . . . . . . . 8 2.7 Authentication Information Extension . . . . . . . . . . . . 8 3. Internationalization Considerations . . . . . . . . . . . . 9 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . 11 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 Normative References . . . . . . . . . . . . . . . . . . . . 13 Informative References . . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . 14 Full Copyright Statement . . . . . . . . . . . . . . . . . . 15 Hollenbeck Expires April 21, 2003 [Page 2] Internet-Draft Extending EPP October 2002 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 Changes from Previous Version (Note to RFC editor: please remove this section completely before publication as an RFC.) None, this is the initial version. Hollenbeck Expires April 21, 2003 [Page 3] Internet-Draft Extending EPP October 2002 2. Principles of Protocol Extension The EPP extension model is based on the XML representation for a wildcard schema component using an 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 such changes 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 XXXX [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 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. Hollenbeck Expires April 21, 2003 [Page 4] Internet-Draft Extending EPP October 2002 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]. 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 element that is sent to a client before Hollenbeck Expires April 21, 2003 [Page 5] Internet-Draft Extending EPP October 2002 the client establishes an interactive session with the server. The element contains zero or more elements that, if present, contain a URI identifying an available extension: S: S: S: S: Example EPP server epp.example.tld S: 2000-06-08T22:00:00.0Z S: S: 1.0 S: en S: fr S: urn:ietf:params:xml:ns:obj1 S: urn:ietf:params:xml:ns:obj2 S: urn:ietf:params:xml:ns:obj3 S: S: urn:ietf:params:xml:ns:foo-ext1 S: http://custom/obj1ext-1.0 S: S: S: S: S: S: S: S: S: S: S: S: In the example above, the server is announcing the availability of two extensions: 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 command before attempting to use any standard commands or extensions. The command contains zero or more elements that, if present, contain a URI identifying an available extension that the client wishes to use during the course of the session: Hollenbeck Expires April 21, 2003 [Page 6] Internet-Draft Extending EPP October 2002 C: C: C: C: C: ClientX C: foo-BAR2 C: bar-FOO2 C: C: 1.0 C: en C: C: C: urn:ietf:params:xml:ns:obj1 C: urn:ietf:params:xml:ns:obj2 C: urn:ietf:params:xml:ns:obj3 C: C: http://custom/obj1ext-1.0 C: C: C: C: ABC-12345 C: C: 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 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. 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]. Hollenbeck Expires April 21, 2003 [Page 7] Internet-Draft Extending EPP October 2002 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.1 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 element information item: Hollenbeck Expires April 21, 2003 [Page 8] Internet-Draft Extending EPP October 2002 3. 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 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]. Hollenbeck Expires April 21, 2003 [Page 9] Internet-Draft Extending EPP October 2002 4. 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. Hollenbeck Expires April 21, 2003 [Page 10] Internet-Draft Extending EPP October 2002 5. 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 XXXX [15]. Hollenbeck Expires April 21, 2003 [Page 11] Internet-Draft Extending EPP October 2002 6. Acknowledgements The author would like to thank the following people who have provided significant contributions to the development of this document: TBD. Hollenbeck Expires April 21, 2003 [Page 12] Internet-Draft Extending EPP October 2002 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", draft-ietf- provreg-epp-07 (work in progress), August 2002. [3] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-xml, October 2000, . [4] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML Schema Part 1: Structures", W3C REC-xmlschema-1, May 2001, . [5] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes", W3C REC-xmlschema-2, May 2001, . [6] Bray, T., Hollander, D. and A. Layman, "Namespaces in XML", W3C REC-xml-names, January 1999, . [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", draft-mealling-iana- xmlns-registry-04 (work in progress), July 2002. [9] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998. Hollenbeck Expires April 21, 2003 [Page 13] Internet-Draft Extending EPP October 2002 Informative References [10] Hollenbeck, S., "Extensible Provisioning Protocol Domain Name Mapping", draft-ietf-provreg-epp-domain-05 (work in progress), August 2002. [11] Rose, M., Masinter, L. and S. Hollenbeck, "Guidelines for The Use of XML within IETF Protocols", draft-hollenbeck-ietf-xml- guidelines-06 (work in progress), August 2002. [12] Hollenbeck, S., "Extensible Provisioning Protocol E.164 Number Mapping", draft-ietf-enum-epp-e164-01 (work in progress), August 2002. [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", draft-iab-sec-cons-01 (work in progress), October 2002. Author's Address Scott Hollenbeck VeriSign, Inc. 21345 Ridgetop Circle Dulles, VA 20166-6503 US EMail: shollenbeck@verisign.com Hollenbeck Expires April 21, 2003 [Page 14] Internet-Draft Extending EPP October 2002 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. Hollenbeck Expires April 21, 2003 [Page 15]