One document matched: draft-greevenbosch-core-profile-description-00.xml

<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'[
<!ENTITY RFC2119 SYSTEM
"/IETF/xml2rfc-1.35/bibxml/reference.RFC.2119.xml">
]>


<?rfc toc="yes"?>
<?rfc symrefs="yes" ?>

<rfc category="info" ipr="trust200902" docName="draft-greevenbosch-core-profile-description-00">
  <front>
    <title abbrev="CoAP Profile Description Format">CoAP Profile Description Format</title>
    <author initials="B." surname="Greevenbosch" fullname="Bert Greevenbosch">
      <organization abbrev="Huawei Technologies">Huawei Technologies Co., Ltd.</organization>
      <address>
        <postal>
          <street>Huawei Industrial Base</street>
          <street>Bantian, Longgang District</street>
          <city>Shenzhen</city>
          <code>518129</code>
          <country>P.R. China</country>
        </postal>
        <phone>+86-755-28978088</phone>
        <email>bert.greevenbosch@huawei.com</email>
      </address>
    </author>
    <date month="June" year="2012"/>
    <area>Applications</area>
    <workgroup>core</workgroup>
    <abstract>
      <t>
         This document provides a profile description format,
         that can be used to express capabilities of a CoAP server.
      </t>
    </abstract>
    <note title="Note">
      <t>
        Discussion and suggestions for improvement are requested, 
        and should be sent to core@ietf.org.
      </t>
    </note>
  </front>
  <middle>
    <section title="Requirements notation">
      <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"/>.
      </t>
    </section>
    <section title="Introduction">
       <t>
          The Constrained Application Protocol (CoAP) <xref target="I-D.ietf-core-coap"/> is a RESTful protocol for constrained nodes 
          and networks. 
       </t>
       <t>
          Often, a client first learns about a resource through the link format <xref target="I-D.ietf-core-link-format"/>.
          The link format only provides basic information,
          for example the resource URL.
          However, it would be good if the client could get more extensive information on the resources when required.
          This document defines a profile description format,
          which can be used to signal several parameters about resources and their servers.  
       </t>
       <t>
          One of the main features of the CoAP protocol is the ability to include CoAP options.
          These options can be either elective or critical.
          A message with an unsupported critical option will be rejected,
          whereas unsupported elective options will be ignored.
       </t>
       <t>
         Even though it is well defined how the server must respond to unsupported options,
         it is useful for the client to know which options are supported in advance.
         In this way,
         it can determine which options are viable to use in a transaction,
         and which features cannot be exploited.
         This specification allows signalling of the supported options by the resource.
       </t>       
       <t>
         Another important feature of a server is which media types it supports.         
         This document allows signalling of that information too. 
       </t>
       <t>
         It is anticipated that more profile descriptions will become available in the future.
       </t>
    </section>
    <section title="The Profile Interface">
      <t>
        The profile description can be obtained through a link with interface type "core#p" 
        (see also <xref target="I-D.shelby-core-interfaces"/>).
        The URI of the profile description should be equal to the URI of the associated resource,
        but with a "/p" suffix.
        For example, if the client wants to get profile description on a server witn URI "www.example.org", 
        it can send a GET request for "coap://www.example.org/p".
      </t>
      <t>
        If the profile of a particular resource is available,
        it should use the same naming convention.        
        For example,
        the profile of the sensor "coap://www.example.org/s/tmp" (on the same server) can be acquired with a GET to:       
        "coap://www.example.org/s/tmp/p".
      </t>
    </section>
    <section title="The Profile Format">
      <t>
         The profile description is formatted as a JSON document.
         It consists of several profile fields,
         each of which has associated parameters.
      </t>
      <section title="The Options "op" profile field">
	      <t>
	         The Options "op" profile field contains a list of options that are supported by a resource.
	         It has the format depicted in <xref target="soformat"/>, 
	         where op1, op2, ... are integers representing the option numbers of the supported options,
	         as defined in <xref target="I-D.ietf-core-coap"/> and/or through IANA. 
	         The option numbers MUST appear in numerical order,
	         starting with the lowest number.
	         <figure title=""op" syntax" anchor="soformat">
	            <artwork align="center">
"op":[op1,op2,...]
	            </artwork>
	         </figure>
	      </t>
	      <t>
	         When including the "op" profile field in the profile description of a resource,
	         all option numbers of the CoAP options supported by that resource MUST be included.
	         Options that are not supported by the resource MUST NOT be included in the "op" profile field.
	      </t>
	      <t>
	         If the "op" profile field is available,
	         the receiving party SHALL assume a non-listed option is not supported by the associated resource.
	      </t>
      </section>
      <section title="The Media-Types "mt" profile field">
         <t>
            The Media-Types "mt" profile field indicates which media-types are supported.
            It has the format depicted in <xref target="mtformat"/>,
            where mt1, mt2, ... are integers representing the media-type numbers of the supported media-types,
            as defined in <xref target="I-D.ietf-core-coap"/> and/or through IANA. 
            The media-type numbers MUST appear in numerical order,
            starting with the lowest number.
            <figure title=""mt" syntax" anchor="mtformat">
               <artwork align="center">
"mt":[mt1,mt2,...]
               </artwork>
            </figure>           
        </t>
        <t>
          When including the "mt" profile field in the profile description of a resource,
          all media-types of the CoAP options supported by that resource MUST be included.
          Media-types that are not supported by the resource MUST NOT be included in the "mt" profile field.
        </t>
        <t>
          If the "mt" profile field is available,
          the receiving party SHALL assume a non-listed media-type is not supported by the associated resource.
        </t>
      </section>      
    </section>
    <section title="Usage with servers, resources and batches" anchor="srbsupport">
      <t>
        A CoAP server may cater for multiple resources.
        In addition,
        the document <xref target="I-D.shelby-core-interfaces"/>
        provides a batch mechanism that allows querying/manipulating multiple resources at once.        
      </t>
      <t>
        The "/p" URI suffix allows obtaining profile description on each of these three levels.
        For example,
        a GET to "http://www.example.org/p" would return profile description about the complete server,
        whereas a GET to "http://www.example.org/s/tmp/p" only returns profile description about the temperature sensor "tmp".
        Lastly, a GET to "http://www.example.org/s/p", 
        where "/s" is a batch of sensors,
        would return common profile description for all these sensors.         
      </t>
      <t>
        The hierarchical nature of these three entities implies that profiles can only become more restrictive when going to a lower level.
        For example, a server may support the block option, 
        whereas one of its resources does not.
        In that case,
        the profile of the server would indicate block option support,
        whereas the profile of the resource would not do so.        
      </t>
    </section>
    <section title="Forward compatibility">
      <t>
        To allow addition of new profile fields in the future,
        unknown profile fields SHOULD be ignored by the client.        
      </t>
    </section>
    <section title="Examples">
      <t>
         The following is an example of a camera sensor at "coap://www.example.org/s/cam",
         that supports the 
         "Content-Type" (1), 
         "Proxy-Uri" (3), 
         "ETag" (4), 
         "Uri-Host" (5),
         "Uri-Port" (7), 
         "Uri-Path" (9), 
         "Token" (11) and
         "Block2" (17)
         options.
      </t>
      <t>
         The supported media types are 
         "text/plan" (0), 
         "application/link-format" (40)
         and "application/json" (50).
      </t>         
         <figure title="">
           <artwork align="center">
Req: GET /s/cam/p
           
Res: 2.05 Content (application/json)
{
  "op":[1,3,4,5,7,9,11,17],
  "mt":[0,40,50]
}
           </artwork>
         </figure>      
    </section>
    <section title="Open topics">
      <t>
         <list style="symbols">
           <t>             
             How to signal the client profile?
           </t>
           <t>
             Which other profile data needs signalling?
           </t>
           <t>
             A natural media type for a camera would be JPEG.
             Therefore the "image/jpeg" media type may need CoAP registration.
           </t>
           <t>
             Currently, 
             support of observe can be signalled in the link format as well as through the mechanism described here.                         
           </t>
           <t>
             <xref target="srbsupport"/> describes the hierchical nature of servers, batches and sensors,
             and how the profiles fit in this hierarchy.
             It is the question how to handle sensors that do not provide profile data.
             One option could be to assume profile description is inherited, 
             unless separately specified.
             This may be reasonable as often the server provides most functionality to all of its resources. 
             However, 
             if we don't allow inheritance of the profile description,             
             it would be needed to specify the profile description for all resources separately.
           </t>
           <t>
             Is it needed to signal the profile description on a resource basis,
             or would it be enough to have only one, associated with the server?
           </t>
           <t>
             Fix the order in which the profile fields must appear?
           </t>
           <t>
             Make a distinction between "critical" and "elective" profile fields?
           </t>
         </list>
      </t>
    </section>
    <section title="Security Considerations">
      <t>
        For general CoAP security considerations see <xref target="I-D.ietf-core-coap"/>. 
      </t>
       <t>
          In an unprotected environment,
          an attacker can change the profile description.
          For example, the list of supported options may be changed.
          This could cause the client to make a wrong decision on which mechanisms to use.
          However, such a threat is normal in environments that lack secure authentication.          
       </t>
    </section>
    <section title="IANA Considerations">
      <t>
        <list style="symbols">
          <t>A registry for profile fields as well as possible values needs to be set up.</t>
          <t>The "core#p" interface must be registered in due time.</t>
        </list>
      </t>
    </section>
    <section title="Acknowledgements">
       <t>
          The author would like to thank Kepeng Li for his ideas and feedback. 
       </t>
    </section>
  </middle>
  <back>
    <references title="Normative References">
       &RFC2119;
    </references>
    <references title="Informative References">
       <reference anchor="I-D.ietf-core-coap">
         <front>
           <title>Constrained Application Protocol (CoAP)</title>
           <author initials="Z." surname="Shelby"/>
           <author initials="K." surname="Hartke"/>
           <author initials="C." surname="Bormann"/>
           <author initials="B." surname="Frank"/>
           <date month="March" year="2012"/>
         </front>
         <seriesInfo name="draft-ietf-core-coap-09" value="(work in progress)" />
       </reference>
       <reference anchor="I-D.ietf-core-link-format">
         <front>
           <title>CoRE Link Format</title>
           <author initials="Z." surname="Shelby"/>
           <date month="May" year="2012"/>
         </front>
         <seriesInfo name="draft-ietf-core-link-format-12" value="(work in progress)" />
       </reference>
       <reference anchor="I-D.shelby-core-interfaces">
         <front>
           <title>CoRE Link Format</title>
           <author initials="Z." surname="Shelby"/>
           <date month="March" year="2012"/>
         </front>
         <seriesInfo name="draft-shelby-core-interfaces-02" value="(work in progress)" />
       </reference>       
    </references>    
  </back>

</rfc>