| J. Gould | |
| J. Faust | |
| VeriSign, Inc. | |
| January 2, 2014 |
Common Object Attribute (COA) Extension for the Extensible Provisioning Protocol (EPP)
verisign_epp-extension_idn-lang_v01
This document describes an Extensible Provisioning Protocol (EPP) extension mapping for attaching additional key, value pair attributes to objects defined in an EPP object mapping like the EPP domain name mapping, the EPP host mapping, and the EPP contact mapping.
COPYRIGHT NOTIFICATION
Copyright 2014 VeriSign, Inc. All rights reserved. VERISIGN; the Verisign logo; and other trademarks, service marks and Verisign designs are registered or unregistered trademarks of VeriSign Inc. and its subsidiaries in the United States and foreign countries. Copyright laws and international treaties protect this document, and any Verisign product to which it relates.
VERISIGN PROPRIETARY INFORMATION
This document is the property of VeriSign, Inc. and its subsidiaries (together "Verisign") It may be used by recipient only for the purpose for which it was transmitted and must be returned upon request or when no longer needed by recipient. It may not be copied or communicated without the prior written consent of Verisign.
NOTICE AND CAUTION
Concerning U.S. Patent or Trademark Rights
Verisign and other trademarks, service marks and logos are registered or unregistered trademarks of Verisign and its subsidiaries in the United States and in foreign countries. The inclusion in this document, the associated on-line file or the associated software of any information covered by any other patent, trademark or service mark rights does not constitute nor imply a grant of or authority to exercise, any right or privilege protected by such patent, trademark or service mark. All such rights and privileges are vested in the patent, trademark or service mark owner and no other person may exercise such rights without express permission, authority or license secured from the patent, trademark or service mark owner.
This document describes an extension mapping for version 1.0 of the Extensible Provisioning Protocol (EPP) [RFC5730]. This mapping, an extension to EPP object mappings like the EPP domain name mapping [RFC5731], for attaching additional key, value pair attributes to objects. The set of objects that support the COA extension and the set of COA keys is up to server policy.
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 [RFC2119].
XML is case sensitive. Unless stated otherwise, XML specifications and examples provided in this document MUST be interpreted in the character case presented in order to develop a conforming implementation.
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 are provided only to illustrate element relationships and are not a REQUIRED feature of this protocol.
"coa-1.0" is used as an abbreviation for "urn:ietf:params:xml:ns:coa-1.0". The XML namespace prefix "coa" is used, but implementations MUST NOT depend on it and instead employ a proper namespace-aware XML parser and serializer to interpret and output the XML documents.
This extension adds additional elements to EPP object mappings like the EPP domain name mapping [RFC5731]. Only those new elements are described here.
The Client Object Attribute (COA) is a client specified key, value pair consisting of a key name and a key value. A Client Object Attribute is represented by the <coa:attr> element with the following child elements:
An example <coa:attr> element with key name "KEY1" and key value of "value1":
<coa:attr> <coa:key>KEY1</coa:key> <coa:value>value1</coa:value> </coa:attr>
The <coa:key> element can also be used outside of a <coa:attr> element in certain contexts where it is only necessary to identify the attribute and not specify its value.
A detailed description of the EPP syntax and semantics can be found in the EPP core protocol specification [RFC5730].
EPP provides three commands to retrieve object information: <check> to determine if an object is known to the server, <info> to retrieve detailed information associated with an object, and <transfer> to retrieve object transfer status information.
This extension does not add any elements to the EPP <check> command or <check> response described in the [RFC5730].
This extension does not add any elements to the EPP <info> command described in the [RFC5730]. Additional elements are defined for the <info> response.
When an <info> command has been processed successfully, the EPP <resData> element MUST contain child elements as described in an object mapping like [RFC5731]. In addition, the EPP <extension> element SHOULD contain a child <coa:infData> element that identifies the extension namespace if the object has one or more Client Object Attributes associated with it and based on server policy. The <coa:infData> element contains the following child elements:
Example <info> response for a domain with an associated Client Object Attribute:
S:<?xml version="1.0" encoding="UTF-8"?> S:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> S: <response> S: <result code="1000"> S: <msg>Command completed successfully</msg> S: </result> S: <resData> S: <domain:infData S: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> S: <domain:name>example.tld</domain:name> S: <domain:roid>EXAMPLE1-REP</domain:roid> S: <domain:status s="ok"/> S: <domain:clID>ClientX</domain:clID> S: <domain:crID>ClientY</domain:crID> S: <domain:crDate>2011-02-04T15:44:37.0526Z S: </domain:crDate> S: <domain:authInfo> S: <domain:pw>2fooBAR</domain:pw> S: </domain:authInfo> S: </domain:infData> S: </resData> S: <extension> S: <coa:infData xmlns:coa= S: "urn:ietf:params:xml:ns:coa-1.0"> S: <coa:attr> S: <coa:key>KEY1</coa:key> S: <coa:value>value1</coa:value> S: </coa:attr> S: </coa:infData> S: </extension> S: <trID> S: <clTRID>54321-CLI</clTRID> S: <svTRID>54321-SER</svTRID> S: </trID> S: </response> S:</epp>
This extension does not add any elements to the EPP <transfer> command or <transfer> response described in the [RFC5730].
EPP provides five commands to transform objects: <create> to create an instance of an object, <delete> to delete an instance of an object, <renew> to extend the validity period of an object, <transfer> to manage object sponsorship changes, and <update> to change information associated with an object.
This extension defines additional elements to extend the EPP <create> command of an object mapping like [RFC5731].
The EPP <create> command provides a transform operation that allows a client to create an object. In addition to the EPP command elements described in an object mapping like [RFC5731], the command MUST contain a child <coa:create> element that identifies the extension namespace if the client wants to associate Client Object Attributes to the object. The <coa:create> element contains the following child elements:
Example <create> command to create a domain object with a Client Object Attribute:
C:<?xml version="1.0" encoding="UTF-8"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <create> C: <domain:create C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.tld</domain:name> C: <domain:authInfo> C: <domain:pw>2fooBAR</domain:pw> C: </domain:authInfo> C: </domain:create> C: </create> C: <extension> C: <coa:create xmlns:coa="urn:ietf:params:xml:ns:coa-1.0"> C: <coa:attr> C: <coa:key>KEY1</coa:key> C: <coa:value>value1</coa:value> C: </coa:attr> C: </coa:create> C: </extension> C: <clTRID>ABC-12345</clTRID> C: </command> C: </epp>
This extension does not add any elements to the EPP <create> response described in the [RFC5730].
This extension does not add any elements to the EPP <delete> command or <delete> response described in the [RFC5730].
This extension does not add any elements to the EPP <renew> command or <renew> response described in the [RFC5730].
This extension does not add any elements to the EPP <transfer> command or <transfer> response described in the [RFC5730].
This extension defines additional elements to extend the EPP <update> command of an object mapping like [RFC5731].
The EPP <update> command provides a transform operation that allows a client to modify the attributes of an object. In addition to the EPP command elements described in the appropriate EPP object mapping, the command MUST contain an <extension> element, and the <extension> element MUST contain a child <coa:update> element that identifies the extension namespace if the client wants to update the Client Object Attributes of the object. The <coa:update> element contains a <coa:put> element to add or update one or more Client Object Attributes, or a <coa:rem> element to remove existing Client Object Attributes. At least one <coa:put> or <coa:rem> element MUST be provided.
The <coa:update> element contains the following child elements:
Example <update> command to add or update a Client Object Attribute "KEY1" with the value "value1":
C:<?xml version="1.0" encoding="UTF-8"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.tld</domain:name> C: <domain:chg/> C: </domain:update> C: </update> C: <extension> C: <coa:update xmlns:coa="urn:ietf:params:xml:ns:coa-1.0"> C: <coa:put> C: <coa:attr> C: <coa:key>KEY1</coa:key> C: <coa:value>value1</coa:value> C: </coa:attr> C: </coa:put> C: </coa:update> C: </extension> C: </command> C:</epp>
Example <update> command to remove the Client Object Attribute "KEY1":
C:<?xml version="1.0" encoding="UTF-8"?> C:<epp xmlns="urn:ietf:params:xml:ns:epp-1.0"> C: <command> C: <update> C: <domain:update C: xmlns:domain="urn:ietf:params:xml:ns:domain-1.0"> C: <domain:name>example.tld</domain:name> C: <domain:chg/> C: </domain:update> C: </update> C: <extension> C: <coa:update xmlns:coa="urn:ietf:params:xml:ns:coa-1.0"> C: <coa:rem> C: <coa:key>KEY1</coa:key> C: </coa:rem> C: </coa:update> C: </extension> C: </command> C:</epp>
This extension does not add any elements to the EPP <update> response described in the [RFC5730].
One schema is presented here that is the EPP Client Object Attribute Extension schema.
The formal syntax presented here is a complete schema representation of the object mapping suitable for automated validation of EPP XML instances. The BEGIN and END tags are not part of the schema; they are used to note the beginning and ending of the schema for URI registration purposes.
BEGIN
<?xml version="1.0" encoding="UTF-8"?>
<schema targetNamespace="urn:ietf:params:xml:ns:coa-1.0"
xmlns:coa="urn:ietf:params:xml:ns:coa-1.0"
xmlns="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<annotation>
<documentation>
Extensible Provisioning Protocol v1.0
extension schema for COA (Client Object Attribute).
</documentation>
</annotation>
<element name="create" type="coa:mapType" />
<element name="update" type="coa:updateType" />
<element name="infData" type="coa:mapType" />
<complexType name="updateType">
<sequence>
<element name="rem" type="coa:remType" minOccurs="0" />
<element name="put" type="coa:mapType" minOccurs="0" />
</sequence>
</complexType>
<!--
A sequence of key/value pairs,
for creating or updating a key/value
pair in the server.
-->
<complexType name="mapType">
<sequence>
<element name="attr" type="coa:attrType"
maxOccurs="unbounded" />
</sequence>
</complexType>
<!-- A single key/value pair -->
<complexType name="attrType">
<all>
<element name="key" type="coa:keyType" />
<element name="value" type="coa:valueType" />
</all>
</complexType>
<!-- A sequence of keys,
for removing key/value pairs in the server. -->
<complexType name="remType">
<sequence>
<element name="key" type="coa:keyType"
maxOccurs="unbounded" />
</sequence>
</complexType>
<simpleType name="keyType">
<restriction base="token">
<maxLength value="50" />
</restriction>
</simpleType>
<simpleType name="valueType">
<restriction base="token">
<maxLength value="1000" />
</restriction>
</simpleType>
<!--
End of schema.
-->
</schema>
END
This document uses URNs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [RFC3688]. One URI assignment must be completed by the IANA.
Registration request for the COA namespace:
Registration request for the extension XML schema:
URI: urn:ietf:params:xml:ns:coa-1.0
Registrant Contact: IESG
XML: See the "Formal Syntax" section of this document.
The mapping extensions described in this document do not provide any security services beyond those described by EPP [RFC5730] and protocol layers used by EPP. The security considerations described in these other specifications apply to this specification as well.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC3688] | Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. |
| [RFC5730] | Hollenbeck, S., "Extensible Provisioning Protocol (EPP)", STD 69, RFC 5730, August 2009. |
| [RFC5731] | Hollenbeck, S., "Extensible Provisioning Protocol (EPP) Domain Name Mapping", STD 69, RFC 5731, August 2009. |