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 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 element that is sent to a client before
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.com
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:
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 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:
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.
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 element information item:
.
[4] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML
Schema Part 1: Structures", W3C REC-xmlschema-1, May 2001,
.
[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]
RFC, FYI, BCP