idnits 2.17.1 draft-ietf-provreg-epp-ext-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 30, 2003) is 7637 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: 'TBD' on line 472 -- Possible downref: Non-RFC (?) normative reference: ref. '3' -- Possible downref: Non-RFC (?) normative reference: ref. '4' -- Possible downref: Non-RFC (?) normative reference: ref. '5' -- Possible downref: Non-RFC (?) normative reference: ref. '6' ** Obsolete normative reference: RFC 2396 (ref. '7') (Obsoleted by RFC 3986) == Outdated reference: A later version (-05) exists of draft-mealling-iana-xmlns-registry-04 == Outdated reference: A later version (-08) exists of draft-ietf-enum-epp-e164-02 -- Obsolete informational reference (is this intentional?): RFC 2279 (ref. '13') (Obsoleted by RFC 3629) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Hollenbeck 3 Internet-Draft VeriSign, Inc. 4 Expires: November 28, 2003 May 30, 2003 6 Guidelines for Extending the Extensible Provisioning Protocol 7 draft-ietf-provreg-epp-ext-03.txt 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC2026. 14 Internet-Drafts are working documents of the Internet Engineering 15 Task Force (IETF), its areas, and its working groups. Note that other 16 groups may also distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at http:// 24 www.ietf.org/ietf/1id-abstracts.txt. 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 This Internet-Draft will expire on November 28, 2003. 31 Copyright Notice 33 Copyright (C) The Internet Society (2003). All Rights Reserved. 35 Abstract 37 The Extensible Provisioning Protocol (EPP) is an application layer 38 client-server protocol for the provisioning and management of objects 39 stored in a shared central repository. Specified in XML, the 40 protocol defines generic object management operations and an 41 extensible framework that maps protocol operations to objects. This 42 document presents guidelines for use of EPP's extension mechanisms to 43 define new features and object management capabilities. 45 Conventions Used In This Document 47 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 48 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 49 document are to be interpreted as described in RFC 2119 [1]. 51 In examples, "C:" represents lines sent by a protocol client and "S:" 52 represents lines returned by a protocol server. Indentation and 53 white space in examples is provided only to illustrate element 54 relationships and is not a REQUIRED feature of this specification. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.1 Changes from Previous Version . . . . . . . . . . . . . . . 3 60 2. Principles of Protocol Extension . . . . . . . . . . . . . . 4 61 2.1 Documenting Extensions . . . . . . . . . . . . . . . . . . . 4 62 2.2 Identifying Extensions . . . . . . . . . . . . . . . . . . . 5 63 2.2.1 Standards Track Extensions . . . . . . . . . . . . . . . . . 5 64 2.2.2 Other Extensions . . . . . . . . . . . . . . . . . . . . . . 5 65 2.3 Extension Announcement and Selection . . . . . . . . . . . . 5 66 2.4 Protocol-level Extension . . . . . . . . . . . . . . . . . . 7 67 2.5 Object-level Extension . . . . . . . . . . . . . . . . . . . 8 68 2.6 Command-Response Extension . . . . . . . . . . . . . . . . . 8 69 2.7 Authentication Information Extension . . . . . . . . . . . . 8 70 3. Selecting an Extension Mechanism . . . . . . . . . . . . . . 9 71 3.1 Mapping and Extension Archives . . . . . . . . . . . . . . . 10 72 4. Internationalization Considerations . . . . . . . . . . . . 11 73 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 12 74 6. Security Considerations . . . . . . . . . . . . . . . . . . 13 75 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 76 Normative References . . . . . . . . . . . . . . . . . . . . 15 77 Informative References . . . . . . . . . . . . . . . . . . . 16 78 Author's Address . . . . . . . . . . . . . . . . . . . . . . 17 79 Intellectual Property and Copyright Statements . . . . . . . 18 81 1. Introduction 83 The Extensible Provisioning Protocol (EPP, [2]) was originally 84 designed to provide a standard Internet domain name registration 85 protocol for use between Internet domain name registrars and domain 86 name registries. However, specific design decisions were made to 87 ensure that the protocol could also be used in other provisioning 88 environments. Specifically: 90 o Extensibility has been a design goal from the very beginning. EPP 91 is represented in the Extensible Markup Language (XML, [3]), and 92 is specified in XML Schema ([4] and [5]) with XML namespaces [6] 93 used to identify protocol grammars. 95 o The EPP core protocol specification describes general protocol 96 functions, not objects to be managed by the protocol. Managed 97 object definitions, such as the mapping for Internet domain names 98 [10] (itself a protocol extension), are loosely coupled to the 99 core specification. 101 o A concentrated effort was made to separate required minimum 102 protocol functionality from object management operating logic. 104 o Several extension mechanisms were included to allow designers to 105 add new features or to customize existing features for different 106 operating environments. 108 This document describes EPP's extensibility features in detail and 109 provides guidelines for their use. Though written specifically for 110 protocol designers considering EPP as the solution to a provisioning 111 problem, anyone interested in using XML to represent IETF protocols 112 might find these guidelines useful. 114 XML is case sensitive. Unless stated otherwise, XML instances and 115 examples provided in this document MUST be interpreted in the 116 character case presented to develop a conforming implementation. 118 1.1 Changes from Previous Version 120 (Note to RFC editor: please remove this section completely before 121 publication as an RFC.) 123 WG last call comments: changed "sold" to "solid" in section Section 124 3.1. 126 2. Principles of Protocol Extension 128 The EPP extension model is based on the XML representation for a 129 wildcard schema component using an element information item (as 130 described in section 3.10.2 of [4]) and XML namespaces [6]. This 131 section provides guidelines for the development of protocol 132 extensions and describes the extension model in detail. 134 Extending a protocol implies the addition of features without 135 changing the protocol itself. In EPP that means that an extension 136 MUST NOT alter an existing protocol schema as such changes result in 137 new versions of an existing schema, not extensions of an existing 138 schema. For example, a designer MUST NOT add new elements to an 139 existing schema and call the result an "extension" of the protocol. 140 The result is a new, non-backwards-compatible version of an existing 141 schema. Extensions MUST adhere to the principles described in this 142 section to be considered valid protocol extensions. 144 EPP extensions MUST be specified in XML. This ensures that parsers 145 capable of processing EPP structures will also be capable of 146 processing EPP extensions. Guidelines for the use of XML in IETF 147 protocols (thus good information for extension designers) can be 148 found in RFC 3470 [11]. 150 A designer MUST remember that extensions themselves MAY also be 151 extensible. A good chain of extensions is one in which the protocol 152 schemas evolve from general functionality to more specific (perhaps 153 even more limited) functionality. 155 2.1 Documenting Extensions 157 The EPP core specification [2] has an appendix that contains a 158 suggested outline to document protocol extensions. Designers are 159 free to use this template or any other format as they see fit, but 160 the extension document SHOULD at a minimum address all of the topics 161 listed in the template. 163 Extension designers need to consider the intended audience and 164 consumers of their extensions. Extensions MAY be documented as 165 Internet-Draft and RFC documents if the designer is facing 166 requirements for coordination, interoperability, and broad 167 distribution, though the intended maturity level (informational, 168 proposed standard, etc.) largely depends on what is being extended 169 and the amount of general interest in the extension. An extension to 170 a standards-track specification with broad interest might well be a 171 candidate for standards track publication, whereas an extension to a 172 standards track specification with limited interest might be better 173 suited for informational publication. 175 Extensions need not be published as Internet-Draft or RFC documents 176 if they are intended for operation in a closed environment or are 177 otherwise intended for a limited audience. In such cases extensions 178 MAY be documented in a file and structural format that is appropriate 179 for the intended audience. 181 2.2 Identifying Extensions 183 An EPP extension is uniquely identified by a Uniform Resource 184 Identifier (URI, defined in RFC 2396 [7]). The URI used to identify 185 the extension MUST also be used to identify the XML namespace 186 associated with the extension. Any valid URI MAY be used to identify 187 an EPP extension, though the selection of a URI form (Uniform 188 Resource Locator (URL) vs. Uniform Resource Name (URN), hierarchical 189 vs. relative, etc.) SHOULD depend on factors such as organizational 190 policies on change control and a balance between locating resources 191 and requirements for persistence. An extension namespace MAY 192 describe multiple extension mechanisms, such as definition of new 193 protocol features, objects, or elements, within the schema used to 194 define the namespace. 196 The following are sample extension-identifying URIs: 198 urn:ietf:params:xml:ns:foo-ext1 200 http://custom/obj1ext-1.0 202 Extension designers MAY include version information in the URI used 203 to identify an extension. If version information is included in the 204 URI, the URI itself will need to change as the extension is revised 205 or updated. 207 2.2.1 Standards Track Extensions 209 URIs for extensions intended for IETF standards track use MUST 210 conform to the URN syntax specifications and registration procedures 211 described in [8]. 213 2.2.2 Other Extensions 215 URIs for extensions that are not intended for IETF standards track 216 use MUST conform to the URI syntax specifications described in RFC 217 2396. 219 2.3 Extension Announcement and Selection 221 An EPP server MUST announce extensions that are available for client 222 use as part of a element that is sent to a client before 223 the client establishes an interactive session with the server. The 224 element contains zero or more elements 225 that, if present, contain a URI identifying an available extension: 227 S: 228 S: 232 S: 233 S: Example EPP server epp.example.com 234 S: 2000-06-08T22:00:00.0Z 235 S: 236 S: 1.0 237 S: en 238 S: fr 239 S: urn:ietf:params:xml:ns:obj1 240 S: urn:ietf:params:xml:ns:obj2 241 S: urn:ietf:params:xml:ns:obj3 242 S: 243 S: urn:ietf:params:xml:ns:foo-ext1 244 S: http://custom/obj1ext-1.0 245 S: 246 S: 247 S: 248 S: 249 S: 250 S: 251 S: 252 S: 253 S: 254 S: 255 S: 256 S: 258 In the example above, the server is announcing the availability of 259 two extensions: 261 urn:ietf:params:xml:ns:foo-ext1, and 263 http://custom/obj1ext-1.0 265 An EPP client MUST establish a session with an EPP server using the 266 EPP command before attempting to use any standard commands or 267 extensions. The command contains zero or more 268 elements that, if present, contain a URI identifying an available 269 extension that the client wishes to use during the course of the 270 session: 272 C: 273 C: 277 C: 278 C: 279 C: ClientX 280 C: foo-BAR2 281 C: bar-FOO2 282 C: 283 C: 1.0 284 C: en 285 C: 286 C: 287 C: urn:ietf:params:xml:ns:obj1 288 C: urn:ietf:params:xml:ns:obj2 289 C: urn:ietf:params:xml:ns:obj3 290 C: 291 C: http://custom/obj1ext-1.0 292 C: 293 C: 294 C: 295 C: ABC-12345 296 C: 297 C: 299 In the example above, the client indicates that it wishes to use an 300 extension identified by the http://custom/obj1ext-1.0 URI during the 301 session established upon successful completion of the 302 command. 304 An EPP server MUST announce all extensions that are publicly 305 available for client use. An EPP client MUST NOT request an 306 extension that has not been announced by the server. An EPP server 307 MAY restrict a client's ability to select an extension based on a 308 client's identity and authorizations granted by the server operator. 310 2.4 Protocol-level Extension 312 EPP defines a set of structures for client-server command-response 313 interaction, but additional structures MAY be added to the protocol. 314 New structure definition is a matter of defining a schema for the 315 structures that defines needed functionality and assigning a URI to 316 uniquely identify the object namespace and schema. Specific 317 protocol-level extension mechanisms are described in section 2.7.1 of 318 the EPP core protocol specification [2]. 320 2.5 Object-level Extension 322 EPP commands and responses do not contain attributes that are 323 specific to any managed object. Every command and response MUST 324 contain elements bound to an object namespace. Object definition is 325 a matter of defining a schema for the object that defines 326 functionality for each needed command and associated response, and 327 assigning a URI to uniquely identify the object namespace and schema. 328 Specific object-level extension mechanisms are described in section 329 2.7.2 of the EPP core protocol specification [2]. 331 2.6 Command-Response Extension 333 EPP command and response structures defined in existing object 334 mappings MAY also be extended. For example, an object mapping that 335 describes general functionality for the provisioning of Internet 336 domain names can be extended to included additional command and 337 response elements needed for the provisioning of domain names that 338 represent E.164 telephone numbers [12]. Specific command-response 339 extension mechanisms are described in section 2.7.1 of the EPP core 340 protocol specification [2]. 342 2.7 Authentication Information Extension 344 Some EPP object mappings, such as the Internet domain name mapping 345 [10], include elements to associate authentication information (such 346 as a password) with an object. The schema for any object mapping 347 that supports authentication information SHOULD be flexible enough to 348 specify multiple forms of authentication information. With XML 349 Schema ([4] and [5]), this can be accomplished by offering an element 350 choice that includes an element information item: 352 354 3. Selecting an Extension Mechanism 356 Extensibility is a powerful feature of XML, but it also provides 357 multiple opportunities to make poor design decisions. There are 358 typically several different ways to accomplish a single task, and 359 while all may "work" (for some definition of "work") one extension 360 form will usually be more appropriate than others to complete a given 361 task. The following sequence of steps can be followed to select an 362 appropriate extension form to solve an extension problem: 364 o Command-Response Extension: Adding elements to an existing object 365 mapping is the simplest form of extension available, and is thus 366 the form that should be explored before any other form is 367 considered. The first question to ask when considering an 368 extension form is thus: 370 Can the task be accomplished by adding to an existing object 371 mapping or changing an existing object mapping slightly? 373 If the answer to this question is "yes", you should consider 374 extending an existing object mapping to complete your task. 375 Knowing where to find object mappings is critical to being able to 376 answer this question; see section Section 3.1 for information 377 describing mapping archives. If the answer to this question is 378 "no", consider an object-level extension next. 380 o Object-level Extension: If there is no existing object mapping 381 that can be extended to meet your requirements, consider 382 developing a new object mapping. The second question to ask when 383 considering an extension form is thus: 385 Can the task be accomplished using the existing EPP command and 386 response structures applied to a new object? 388 If the answer to this question is "yes", you should consider 389 developing a new object mapping to complete your task. A new 390 object mapping should differ significantly from existing object 391 mappings; if you find that a new mapping is replicating a 392 significant number of structures found in an existing mapping you 393 probably answered the command-response question incorrectly. If 394 the answer to this question is "no", consider a protocol-level 395 extension next. 397 o Protocol-level Extension: If there is no existing object mapping 398 that can be extended to meet your requirements and the existing 399 EPP command and response structures are insufficient, consider 400 developing new protocol commands, responses, or other structures. 401 The third and final question to ask when considering an extension 402 form is thus: 404 Can the task be accomplished by adding new EPP commands, 405 responses, or other structures applied to new or existing 406 objects? 408 If the answer to this question is "no", EPP can not be used 409 directly to complete your task. If the answer to this question is 410 "yes, extend the protocol by defining new operational structures. 412 The extension forms and decision points listed here are presented in 413 order of complexity. Selecting an extension form without careful 414 consideration of the available extension options can add complexity 415 without any gain in functionality. 417 3.1 Mapping and Extension Archives 419 Existing object mappings are a critical resource when trying to 420 select an appropriate extension form. Existing mappings or 421 extensions can provide a solid basis for further extension, but 422 designers have to know where to find them to consider them for use. 424 Several organizations maintain archives of XML structures that can be 425 useful extension platforms. These include: 427 o The IETF: Object mappings and other extensions have been 428 documented in RFCs and Internet-Drafts. 430 o IANA: Guidelines and registration procedures for an IANA XML 431 registry used by the IETF are described in "The IETF XML Registry" 432 [8]. 434 o OASIS [16]: OASIS maintains an XML archive containing schema 435 definitions for use in the business applications of XML. 437 o XML.org [17]: XML.org maintains an XML archive containing schema 438 definitions for use in multiple industries. 440 o Other archives are likely in the future. Consult your favorite 441 Internet search engine for additional resources. 443 4. Internationalization Considerations 445 EPP is represented in XML [3], which requires conforming parsers to 446 recognize both UTF-8 [13] and UTF-16 [14]; support for other 447 character encodings is also possible. EPP extensions MUST observe 448 both the Internationalization Considerations described in the EPP 449 core protocol specification [2] and IETF policy on the use of 450 character sets and languages described in RFC 2277 [9]. 452 5. IANA Considerations 454 This memo has no direct impact on the IANA. Guidelines for 455 extensions that require IANA action are described in Section 2.2.1. 457 6. Security Considerations 459 EPP extensions inherit the security services of the protocol 460 structure that's being extended. For example, an extension of an 461 object mapping inherits all of the security services of the object 462 mapping. Extensions MAY specify additional security services, such 463 as services for peer entity authentication, confidentiality, data 464 integrity, authorization, access control, or non-repudiation. 465 Extensions MUST NOT mandate removal of security services available in 466 the protocol structure being extended. 468 Protocol designers developing EPP extensions need to be aware of the 469 security threats to be faced in their intended operating environment 470 so that appropriate security services can be provided. Guidelines for 471 designers to consider and suggestions for writing an appropriate 472 Security Considerations section can be found in RFC [TBD] [15]. 474 7. Acknowledgements 476 The author would like to thank the following people who have provided 477 significant contributions to the development of this document: 479 TBD. 481 Normative References 483 [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement 484 Levels", BCP 14, RFC 2119, March 1997. 486 [2] Hollenbeck, S., "Extensible Provisioning Protocol", 487 draft-ietf-provreg-epp-09 (work in progress), March 2003. 489 [3] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler, 490 "Extensible Markup Language (XML) 1.0 (2nd ed)", W3C REC-xml, 491 October 2000, . 493 [4] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML 494 Schema Part 1: Structures", W3C REC-xmlschema-1, May 2001, 495 . 497 [5] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes", W3C 498 REC-xmlschema-2, May 2001, . 500 [6] Bray, T., Hollander, D. and A. Layman, "Namespaces in XML", W3C 501 REC-xml-names, January 1999, . 504 [7] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource 505 Identifiers (URI): Generic Syntax", RFC 2396, August 1998. 507 [8] Mealling, M., "The IETF XML Registry", 508 draft-mealling-iana-xmlns-registry-04 (work in progress), July 509 2002. 511 [9] Alvestrand, H., "IETF Policy on Character Sets and Languages", 512 BCP 18, RFC 2277, January 1998. 514 Informative References 516 [10] Hollenbeck, S., "Extensible Provisioning Protocol Domain Name 517 Mapping", draft-ietf-provreg-epp-domain-07 (work in progress), 518 April 2003. 520 [11] Hollenbeck, S., Rose, M. and L. Masinter, "Guidelines for the 521 Use of Extensible Markup Language (XML) within IETF Protocols", 522 BCP 70, RFC 3470, January 2003. 524 [12] Hollenbeck, S., "Extensible Provisioning Protocol E.164 Number 525 Mapping", draft-ietf-enum-epp-e164-02 (work in progress), 526 February 2003. 528 [13] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC 529 2279, January 1998. 531 [14] Hoffman, P. and F. Yergeau, "UTF-16, an encoding of ISO 10646", 532 RFC 2781, February 2000. 534 [15] Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on 535 Security Considerations", draft-iab-sec-cons-03 (work in 536 progress), February 2003. 538 URIs 540 [16] 542 [17] 544 Author's Address 546 Scott Hollenbeck 547 VeriSign, Inc. 548 21345 Ridgetop Circle 549 Dulles, VA 20166-6503 550 US 552 EMail: shollenbeck@verisign.com 554 Intellectual Property Statement 556 The IETF takes no position regarding the validity or scope of any 557 intellectual property or other rights that might be claimed to 558 pertain to the implementation or use of the technology described in 559 this document or the extent to which any license under such rights 560 might or might not be available; neither does it represent that it 561 has made any effort to identify any such rights. Information on the 562 IETF's procedures with respect to rights in standards-track and 563 standards-related documentation can be found in BCP-11. Copies of 564 claims of rights made available for publication and any assurances of 565 licenses to be made available, or the result of an attempt made to 566 obtain a general license or permission for the use of such 567 proprietary rights by implementors or users of this specification can 568 be obtained from the IETF Secretariat. 570 The IETF invites any interested party to bring to its attention any 571 copyrights, patents or patent applications, or other proprietary 572 rights which may cover technology that may be required to practice 573 this standard. Please address the information to the IETF Executive 574 Director. 576 Full Copyright Statement 578 Copyright (C) The Internet Society (2003). All Rights Reserved. 580 This document and translations of it may be copied and furnished to 581 others, and derivative works that comment on or otherwise explain it 582 or assist in its implementation may be prepared, copied, published 583 and distributed, in whole or in part, without restriction of any 584 kind, provided that the above copyright notice and this paragraph are 585 included on all such copies and derivative works. However, this 586 document itself may not be modified in any way, such as by removing 587 the copyright notice or references to the Internet Society or other 588 Internet organizations, except as needed for the purpose of 589 developing Internet standards in which case the procedures for 590 copyrights defined in the Internet Standards process must be 591 followed, or as required to translate it into languages other than 592 English. 594 The limited permissions granted above are perpetual and will not be 595 revoked by the Internet Society or its successors or assignees. 597 This document and the information contained herein is provided on an 598 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 599 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 600 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 601 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 602 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 604 Acknowledgement 606 Funding for the RFC Editor function is currently provided by the 607 Internet Society.