<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
     There has to be one entity for each item to be referenced. 
     An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3688 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3688.xml">
<!ENTITY RFC5730 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5730.xml">
<!ENTITY RFC5731 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5731.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs), 
     please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
     (Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc private="VeriSign Inc. Proprietary Information" ?>
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space 
     (using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="yes"?>
<!-- keep one blank line between list items -->
<?rfc comments="yes" ?>
<!-- show cref output -->
<?rfc inline="yes" ?>
<!-- inline cref output -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="info" docName="verisign_epp-extension_coa_v02" ipr="none">
  <!-- category values: std, bcp, info, exp, and historic
     ipr values: full3667, noModification3667, noDerivatives3667
     you can add the attributes updates="NNNN" and obsoletes="NNNN" 
     they will automatically be output with "(if approved)" -->

  <!-- ***** FRONT MATTER ***** -->

  <front>
    <title abbrev="coa">Common Object Attribute (COA) Extension for the Extensible Provisioning Protocol (EPP)</title>

    <author fullname="James Gould" initials="J.G" surname="Gould">
      <organization>VeriSign, Inc.</organization>

      <address>
        <postal>
          <street>12061 Bluemont Way</street>

          <city>Reston</city>

          <region>VA</region>

          <code>20190</code>

          <country>US</country>
        </postal>

        <email>jgould@verisign.com</email>

        <uri>http://www.verisigninc.com</uri>
      </address>
    </author>

    <author fullname="Jeffrey Faust" initials="J.F" surname="Faust">
      <organization>VeriSign, Inc.</organization>

      <address>
        <postal>
          <street>12061 Bluemont Way</street>

          <city>Reston</city>

          <region>VA</region>

          <code>20190</code>

          <country>US</country>
        </postal>

        <email>jfaust@verisign.com</email>

        <uri>http://www.verisigninc.com</uri>
      </address>
    </author>


    <date day="2" month="January" year="2014"/>

    <abstract>
      <t>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.</t>
    </abstract>
    
    <note title="Legal Disclaimer">
      <t>COPYRIGHT NOTIFICATION</t>
      <t>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.</t>
      
      <t>VERISIGN PROPRIETARY INFORMATION</t>
      <t>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.</t>

      <t>NOTICE AND CAUTION</t>
      <t>Concerning U.S. Patent or Trademark Rights</t>
      <t>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.</t>    
    </note>
    
  </front>

  <middle>
    <section title="Introduction">
      <t>This document describes an extension mapping for version 1.0 of the
      <xref target="RFC5730">Extensible Provisioning Protocol (EPP)</xref>.
      This mapping, an extension to EPP object mappings like the <xref
      target="RFC5731">EPP domain name mapping</xref>, 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.</t>

      <section title="Conventions Used in This Document">
        <t>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 <xref
        target="RFC2119">RFC 2119</xref>.</t>

        <t>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.</t>
        
        <t>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.        
        </t>

        <t>"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.</t>
      </section>
    </section>

    <section anchor="attrs" title="Object Attributes">
    
      <t>This extension adds additional elements to EPP object mappings like the <xref
      target="RFC5731">EPP domain name mapping</xref>. Only those new elements
      are described here.</t>
      
      <section anchor="coaAttribute" title="Client Object Attribute">
        
        <t>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 &lt;coa:attr&gt; element with the following child elements:</t>
        
        <t><list hangIndent="4" style="hanging">
        
           <t hangText="&lt;coa:key&gt;">Element that contains a key name of 50 or less characters.</t>
         
           <t hangText="&lt;coa:value&gt;">Element that contains a key value of 1000 or less characters.</t>
      
        </list></t>
        
        
       <figure>
            <preamble>An example &lt;coa:attr&gt; element with key name "KEY1" and key value of "value1":</preamble>

            <artwork><![CDATA[
<coa:attr>
  <coa:key>KEY1</coa:key>
  <coa:value>value1</coa:value>
</coa:attr>]]></artwork>
       </figure>
        
      </section>
 
      <section anchor="coaKey" title="Key">
        
        <t>The &lt;coa:key&gt; element can also be used outside of a &lt;coa:attr&gt; element in certain contexts 
        where it is only necessary to identify the attribute and not specify its value.</t>
        
      </section>
 
 
    </section>

    <section anchor="commands" title="EPP Command Mapping">
      <t>A detailed description of the EPP syntax and semantics can be found
      in the EPP core protocol specification <xref target="RFC5730"/>.</t>
      
      <section anchor="queryCommands" title="EPP Query Commands">
      
        <t>EPP provides three commands to retrieve object information: &lt;check&gt; to determine 
        if an object is known to the server, &lt;info&gt; to retrieve detailed information associated 
        with an object, and &lt;transfer&gt; to retrieve object transfer status information.</t>

      <section anchor="checkCommand" title="EPP &lt;check&gt; Command">
      
       <t>This extension does not add any elements to the EPP &lt;check&gt; command 
       or &lt;check&gt; response described in the <xref target="RFC5730"/>.</t>
             
      </section>

      <!-- end CHECK command -->

      <section anchor="infoCommand" title="EPP &lt;info&gt; Command">
      
       <t>This extension does not add any elements to the EPP &lt;info&gt; command 
       described in the <xref target="RFC5730"/>.  Additional elements are defined for the &lt;info&gt; response.</t>  
        
       <t>When an &lt;info&gt; command has been processed successfully, the EPP &lt;resData&gt; element MUST contain child elements as described in an object mapping like <xref target="RFC5731"/>. 
       In addition, the EPP &lt;extension&gt; element SHOULD contain a child &lt;coa:infData&gt; 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 &lt;coa:infData&gt; element contains the following child elements:</t>
        
       <t><list hangIndent="4" style="hanging">
          <t hangText="&lt;coa:attr&gt;">One or more &lt;coa:attr&gt; elements, as described 
          in <xref target="coaAttribute"/>, for the Client Object Attributes set on the object.</t>
       </list></t>
        
        
       <figure>
            <preamble>Example &lt;info&gt; response for a domain with an associated Client Object Attribute:</preamble>

            <artwork><![CDATA[
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>
]]></artwork>
       </figure>

      </section>
      <!-- end INFO command -->
      
      <section anchor="transferQueryCommand" title="EPP &lt;transfer&gt; Command">
      
       <t>This extension does not add any elements to the EPP &lt;transfer&gt; command 
       or &lt;transfer&gt; response described in the <xref target="RFC5730"/>.</t>

      </section>
      <!-- end TRANSFER QUERY command -->
      
      </section>
      
      <section anchor="transformCommands" title="EPP Transform Commands">
      
        <t>EPP provides five commands to transform objects: &lt;create&gt; to create an instance of an object, 
        &lt;delete&gt; to delete an instance of an object, &lt;renew&gt; to extend the validity period of an object,
        &lt;transfer&gt; to manage object sponsorship changes, and &lt;update&gt; to change information associated 
        with an object.</t>

      <section anchor="createCommand" title="EPP &lt;create&gt; Command">
      
       <t>This extension defines additional elements to extend the EPP
        &lt;create&gt; command of an object mapping like <xref target="RFC5731"/>.</t>
        
       <t>The EPP &lt;create&gt; 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 <xref target="RFC5731"/>, the command MUST contain a 
       child &lt;coa:create&gt; element that identifies the extension namespace if the client 
       wants to associate Client Object Attributes to the object.  
       The &lt;coa:create&gt; element contains the following child elements:</t>
       
       <t><list hangIndent="4" style="hanging">
          <t hangText="&lt;coa:attr&gt;">One or more &lt;coa:attr&gt; elements, as described 
          in <xref target="coaAttribute"/>, for the Client Object Attributes to set on the object.</t>
       </list></t>
       
              
       <figure>
            <preamble>Example &lt;create&gt; command to create a domain object with a Client Object Attribute:</preamble>

            <artwork><![CDATA[
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>]]></artwork>
       </figure>
       
       <t>This extension does not add any elements to the EPP &lt;create&gt; response described 
       in the <xref target="RFC5730"/>.</t>      
       
      </section>
      <!-- end CREATE command -->

      <section anchor="deleteCommand" title="EPP &lt;delete&gt; Command">
      
       <t>This extension does not add any elements to the EPP &lt;delete&gt; command 
       or &lt;delete&gt; response described in the <xref target="RFC5730"/>.</t>
         
      </section>
      <!-- end DELETE command -->

      <section anchor="renewCommand" title="EPP &lt;renew&gt; Command">
      
       <t>This extension does not add any elements to the EPP &lt;renew&gt; command 
       or &lt;renew&gt; response described in the <xref target="RFC5730"/>.</t>
       
      </section>
      <!-- end RENEW command -->
      
      <section anchor="transferCommand" title="EPP &lt;transfer&gt; Command">
      
       <t>This extension does not add any elements to the EPP &lt;transfer&gt; command 
       or &lt;transfer&gt; response described in the <xref target="RFC5730"/>.</t>
       
      </section>
      <!-- end TRANSFER command -->
      
      <section anchor="updateCommand" title="EPP &lt;update&gt; Command">
      
       <t>This extension defines additional elements to extend the EPP
        &lt;update&gt; command of an object mapping like <xref target="RFC5731"/>.</t>
        
       <t>The EPP &lt;update&gt; 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 &lt;extension&gt; element, and the 
       &lt;extension&gt; element MUST contain a child &lt;coa:update&gt; element that identifies the extension namespace 
       if the client wants to update the Client Object Attributes of the object.  
       The &lt;coa:update&gt; element contains a &lt;coa:put&gt; element 
       to add or update one or more Client Object Attributes, 
       or a &lt;coa:rem&gt; element to remove existing Client Object Attributes. 
       At least one &lt;coa:put&gt; or &lt;coa:rem&gt; element MUST be provided.</t>
        
       <t>The &lt;coa:update&gt; element contains the following child elements:</t>
       
       <t><list hangIndent="4" style="hanging">
          <t hangText="&lt;coa:rem&gt;">OPTIONAL element that is used to remove Client Object Attributes from the object.  
          The &lt;coa:rem&gt; element MUST contain one or more &lt;coa:key&gt; elements that are used to remove 
          the existing Client Object Attributes.</t>
          
          <t hangText="&lt;coa:put&gt;">OPTIONAL element that is used to add or update Client Object Attributes.  
          The &lt;coa:put&gt; element MUST contain one or more &lt;coa:attr&gt; elements that are each used 
          to identify the name and value of a Client Object Attribute being added to the object or 
          updated if the Client Object Attribute already exists.</t>
       </list></t>
       
              
       <figure>
            <preamble>Example &lt;update&gt; command to add or update a Client Object Attribute 
            "KEY1" with the value "value1":</preamble>

            <artwork><![CDATA[
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>]]></artwork>
       </figure>
  
       <figure>
            <preamble>Example &lt;update&gt; command to remove the Client Object Attribute 
            "KEY1":</preamble>

            <artwork><![CDATA[
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>]]></artwork>
       </figure>
  
  
       <t>This extension does not add any elements to the EPP &lt;update&gt; response described 
       in the <xref target="RFC5730"/>.</t>
        
      </section>
      <!-- end UPDATE command -->

    </section>
      
    </section>

    <!-- EPP command mapping -->

    <section anchor="syntax" title="Formal Syntax">
    
      <t>One schema is presented here that is the EPP Client Object Attribute Extension
      schema.</t>
      
      <t>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.</t>

    <section title="Client Object Attribute Extension Schema">

      <figure>
        <artwork><![CDATA[
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]]></artwork>
      </figure>
      </section>
    </section>
   
   <section title="Change History">
    <section title="Version 01" anchor="version-01">
      <t><list style="numbers">
        <t>Initial version of Internet-Draft format of the 
        Verisign Client Object Attribute, version 1.0.</t>
      </list></t>
    </section>
    <section title="Version 02" anchor="version-02">
      <t><list style="numbers">
        <t>Fixed typo of &quot;caa&gt; to &lt;coa&gt;, based on Designated Expert (DE) review.</t>
      </list></t>
    </section>
   </section>
    
    <section anchor="IANA" title="IANA Considerations">
         <t>
             This document uses URNs to describe XML namespaces and XML schemas
             conforming to a registry mechanism described in <xref target="RFC3688"/>.
             One URI assignment must be completed by the IANA.
         </t>

         <t>Registration request for the COA namespace:</t>
         
         <t>Registration request for the extension XML schema:</t>
         
         <t>URI: urn:ietf:params:xml:ns:coa-1.0</t>
         
         <t>Registrant Contact: IESG</t>
          
         <t>XML: See the "Formal Syntax" section of this document.</t>
 
    </section>


    <section anchor="Security" title="Security Considerations">
      <t>The mapping extensions described in this document do not provide any
      security services beyond those described by <xref
      target="RFC5730">EPP</xref> and protocol layers used by EPP. The security
      considerations described in these other specifications apply to this
      specification as well.</t>
    </section>

  </middle>

  <!--  *****BACK MATTER ***** -->

  <back>
    <!-- References split into informative and normative -->

    <!-- There are 2 ways to insert reference entries from the citation libraries:
     1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
     2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
        (for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")

     Both are cited textually in the same manner: by using xref elements.
     If you use the PI option, xml2rfc will, by default, try to find included files in the same
     directory as the including file. You can also define the XML_LIBRARY environment variable
     with a value containing a set of directories to search.  These can be either in the local
     filing system or remote ones accessed by http (http://domain/dir/... ).-->

    <references title="Normative References">
       
      &RFC2119;
      
      &RFC3688;      

      &RFC5730;

      &RFC5731;

    </references>
  </back>

  <!-- vim: set ts=2 sw=2 expandtab: -->
</rfc>
