<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
     which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [

<!ENTITY RFC2119      PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY COAP         PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-coap.xml'>
<!ENTITY BLOCK        PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-block.xml'>
<!ENTITY LINK-FORMAT  PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-link-format.xml'>
]>

<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>

<rfc
  category="std"
  ipr="trust200902"
  docName="draft-li-core-coap-size-option-02">

  <front>
    <title abbrev="CoAP-Size-Option">
    CoAP Option Extension : Size
    </title>

    <author initials="K." surname="Li" fullname="Kepeng Li">
      <organization abbrev="Huawei Technologies">Huawei Technologies</organization>
      <address>
        <postal>
          <street>Huawei Base, Bantian, Longgang District</street>
          <city>Shenzhen</city>
          <region>Guangdong</region>
          <code>518129</code>
          <country>P. R. China</country>
        </postal>
        <phone>+86-755-28974289</phone>
        <email>likepeng@huawei.com</email>
      </address>
    </author>
    
    <author initials='L.' surname="Tian" fullname='Linyi Tian'>
      <organization>Huawei Technologies</organization>
      <address>
        <postal>
          <street>Huawei Base, Bantian, Longgang District</street>
          <city>Shenzhen</city>
          <region>Guangdong</region>
          <code>518129</code>
          <country>P. R. China</country>
        </postal>
        <phone>+86-755-28978078</phone>
        <email>tianlinyi@huawei.com</email>
      </address>
    </author>
    
    <author initials='B.' surname="Leiba" fullname='Barry Leiba'>
      <organization>Huawei Technologies</organization>
      <address>
        <phone>+1 646 827 0648</phone>
        <email>barryleiba@computer.org</email>
        <uri>http://internetmessagingtechnology.org/</uri>
      </address>
    </author>
    
    <date year="2011" />

    <area>Applications</area>
    <workgroup>core</workgroup>

    <abstract>
      <t>
      This document defines an extension to the Constrained Application Protocol (CoAP) 
      to add a new option Size, 
      which is used to indicate the resource size in a  
      PUT/POST request or in a GET response.
      </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 anchor="intro" title="Introduction">
      <t>
        This specification adds a new option Size to the Constrained Application
         Protocol (CoAP). 
         The main purpose is to indicate the resource size in 
         a PUT/POST request, or in a GET response.
      </t>
      
      <section anchor="just" title="Justification">
        <t>
          If the requester wants to retrieve large resource data using a GET request, 
          it is better to know in advance the size of the resource data. 
          Currently in the Link Format <xref target='I-D.ietf-core-link-format' />
          specification, the maximum size estimate attribute "sz" is defined to 
          give an indication of the estimated maximum size of the resource data.
          By using this, the requester is able to know whether it is capable to accept
          the resource data. However it is not possible for the requester to know exactly 
          how many blocks will be transmitted, therefore, concurrent GET can't be supported. 
        </t>
        <t> 
           Also in a POST/PUT request (for example, a firmware update), 
           it is not possible for the recipient to know in advance what is the size of 
           the data to be transmitted. According to the current CoAP 
           <xref target='I-D.ietf-core-coap' /> specification, when transmitting large data, 
           the recipient will return an error code 4.13 (Request Entity Too Large) 
           to the requester when the data size is too big to be accepted by the recipient.
           In this case the whole transmission has failed, and the previous received data 
           will be useless. This is a waste of transmission resources. 
        </t>
        <t>
          This document adds the new Size Option to provide the capability to indicate
          the accurate size in a GET response or in a POST/PUT request.
         </t>
        <t> 
          By using the Size Option in a GET response, the CoAP Server can let the requester
          know the actual size of the resource in advance.
          This is especially useful for large resources,
          and can facilitate the requester to allocate enough buffer space before transmission.
          Also, using the block size, 
          the requester can calculate the total number of blocks and can use concurrent GET
          requests to retrieve resource data using the Block Option.
          Finally, the recipient can check the resource size after the data transmission has
           been completed.
        </t>
        <t>  
          By using the Size Option in a PUT/POST request, the requester can
          indicate the resource size in the first Block Option message, to let
          the recipient know the resource data size in advance. If the recipient
          is not able to receive the data with the indicated size, the
          recipient can tell the requester in a response code, avoiding the
          cost of the actual data transmission.
        </t>
      </section>

      <section anchor="terms" title="Terminology">
        <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>

    <section anchor="Size" title="Size Option Extension">
      <section anchor="Definition" title="Size Option Definition">
      <t>
      <figure>
         <artwork>
        +------+-----+-------+-----------+--------+---------------+
        | Type | C/E | Name  | Data type | Length | Default       |
        +------+-----+-------+-----------+--------+---------------+
        |  18  |  E  | Size  | uint      | 0-4 B  |               |
        +------+-----+-------+-----------+--------+---------------+
         </artwork>
      </figure>   
      </t>
      </section>
      
      <section anchor="Usage" title="Using the Size Option">        
      <t>
      The Size Option is used to indicate the size of the resource data measured in
      bytes.
      </t>
      <t>
      The GET request including Size=0 is treated as a request to get the size of 
      the resource representation (but not the resource payload).
      </t>
      <t>
      The GET request including an empty Size option is treated as a 
      request to get the size of the resource representation with the resource payload.
      </t>
      <t>
      The Size option
      MUST be included in the GET response, if the Size option is present in the request.
      </t>
      <t>
      Also it SHOULD be used in a POST/PUT request in the first Block Option message.
      </t> 
      <t>
      The Size option SHOULD be included for resources larger than a single PDU, 
      if the Size information is available. And it MAY be included for resources 
      smaller than a single MTU. 
      </t>
      <t>
      In the absence of the option, the size of the resource data is calculated 
      after the data has been transmitted to the recipient,
      either from the CoAP payload length or based on number of blocks and block size.
      </t>
      <t>
      If the Size option is specified it SHOULD be accurate at that time, and SHOULD NOT
      be an estimate.
      </t> 
      <t>
      But due to the dynamic change of the resource data, the Size may not be accurate.
      If the value of Size option is not the same as the actual transmitted data, the
      recipient MUST take the size of the actual transmitted data as accurate, and ignore
      the Size option. In case that the recipient gets all the data but it is still 
      smaller than the announced Size, the recipient SHOULD stop the transmission. 
      If the recipient
      finds out the transmitted data reaches the Size limit, and there's more data
      left, the recipient SHOULD continue to transmit the remaining data.
      </t>
      <t>
      This option is "Elective".  It MUST NOT occur more than once.
      </t>
      </section>
   </section>
   
   <section anchor="Interaction" title="Interaction with Block option">   
      <section anchor="Request" title="Usage in POST/PUT Request">
        <t>
           In a PUT/POST request for large resource data, the requester SHOULD use the Size 
           option to indicate the size of the resource. 
           If the recipient is not capable to receive the data with the indicated size, 
          the recipient MUST return a 4.13
          (Request Entity Too Large) response code to the requester,
          and the data transmission is avoided,
          so that the cost of the actual data transmission is saved.
        </t>
      </section>
     
      <section anchor="Response" title="Usage in GET Response">
        <t>
           In a GET response for large resource data, the CoAP Server SHOULD use the Size option
           to indicate the resource size and return the first block data. The requester can 
           calculate the number of blocks to be transferred based on the block size and the 
           resource size, and use concurrent GET requests to retrieve resource data.
           Also, when the client determines it cannot process data of this Size, it MAY choose
            to abort and not to send subsequent GETs.
        </t>
      </section>        
   </section>
   
    <section anchor="Block" title="How to merge into Block draft">
        <t>
           This section introduces how to merge the Size option draft into Block draft with
           the minimum functionalities.            
        </t>
        <section title="The Size option">
          <t>
           This section will work as section 2.3 in Block draft.
          </t>
          <t>
           <figure>
            <artwork>
        +------+-----+-------+-----------+--------+---------------+
        | Type | C/E | Name  | Data type | Length | Default       |
        +------+-----+-------+-----------+--------+---------------+
        |  18  |  E  | Size  | uint      | 1-4 B  |               |
        +------+-----+-------+-----------+--------+---------------+
           </artwork>
          </figure>   
         </t>
        </section>
        <section title="Using the Size option">
         <t>
           This section will work as section 2.4 in Block draft. 
         </t>
         <t>
           The Size Option is used to indicate the size of the resource data 
           measured in bytes.
         </t>
         <t>
         The Size option SHOULD be used in a POST/PUT request in the first Block 
         Option message.
           If the recipient is not capable to receive the data with the indicated size, 
          the recipient MUST return a 4.13
          (Request Entity Too Large) response code to the requester,
          and the data transmission is avoided,
          so that the cost of the actual data transmission is saved.
        </t>
        <t>
        For a GET request, if it includes an empty Size option, the Size option
         MUST be included in the response. If the GET request includes a Block option,
         the Size option SHOULD be included in the first Block response. 
         In other cases the GET response MAY contain a Size option.
        </t>
          <t>
          If the Size option is specified, it SHOULD be accurate at that time, and 
          SHOULD NOT be an estimate.
         </t> 
          <t>
          The option is "Elective".  It MUST NOT occur more than once.
          </t>
        </section>
        <section title="Example">
          <t>
          Example as indicated as Figure 2 in this draft can be added in section 3 in
          the Block draft.
          </t>
        </section>
   </section>   
   
   <section anchor="example" title="Examples">
      <t>
        This section gives a number of short examples with message flows to illustrate 
        the use of Size option in a GET response, or in a PUT/POST request.
      </t>
      <t>
         The first example (Figure 1) shows that the requester does not know the resource
          data size, and sends the GET request, the recipient can send back the resource size
          using the Size option and the first block. In the subsequent GET
       request, the requester can calculate the number of blocks and use concurrent GET requests
       to retrieve the resource data.      
      </t>
   
   <figure>
         <artwork> <![CDATA[
   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], GET, /status                     ------> |
     |                                                          |
     | <------   ACK [MID=1234], 2.00 OK, 0/1/128, Size: 5000   |
     |                                                          |
     | CON [MID=1235], GET, /status, 1/0/128            ------> |
     |                                                          |
     | <------   ACK [MID=1235], 2.00 OK, 1/1/128               |
     |                                                          |
     |                  ... ...                                 |  
     |                                                          |   
     | CON [MID=1280], GET, /status, 40/0/128           ------> |
     |                                                          |
     | <------   ACK [MID=1280], 2.00 OK, 40/0/128              |
     |                                                          |

                      Figure 1: Size Option in a GET response
     ]]>    </artwork>
     </figure>
     
     <t>
         The second example (Figure 2) shows the requester sending a PUT request with
         the Size option to indicate the resource data size, and since the recipient 
         determines that
         the resource data is too large to be accepted, 
         it sends back a 4.13 (Request Entity Too Large) response code.

      </t>
   
   <figure>
         <artwork> <![CDATA[
   CLIENT                                                     SERVER
     |                                                          |
     | CON [MID=1234], PUT, /options, 1/0/128, Size: 5000 ----> |
     |                                                          |
     | <------   ACK [MID=1234], 4.13 Request Entity Too Large  |
     |                                                          |  

                      Figure 2: Size Option in a PUT request
     ]]>     </artwork>
     </figure>  
                      
    </section> 
   
   
      <section anchor="security" title="Security Considerations">
      <t>
        As the size option is used to determine whether or not the reciepient
        will accept the data, lying about it can cause the recipient to make a 
        wrong decision. For example, an attacker might reduce the reported size
         such that the recipient will accept, even when it cannot process the 
         complete data. 
       </t>
       <t>  
         Related is another attack, where the attacker changes the reported 
         size to a higher value, leading to the recipient rejecting even when 
         it has the capability to receive.
       </t>
       <t>  
         The latter attack is similar to an attack where the attacker blocks 
         the packets altogether; although it is more efficient since the attacker 
         only needs to modify one message. The former attack needs serious consideration
          at implementation level, especially concerning possible buffer overflows
           that might lead to data leaking into the code.
      </t>
    </section>


    <section anchor="iana" title="IANA Considerations">
      <t>
        The IANA is requested to add the following Option Number entry.
      </t>
      
      <figure>
         <artwork>
                +--------+---------------+----------------+
                | Number | Name          | Reference      |
                +--------+---------------+----------------+
                |  18    | Size          | Section 2      |
                +--------+---------------+----------------+
         </artwork>
      </figure>
    </section> 
    
    <section anchor="acknowledgement" title="Acknowledgements">
      <t>
        The authors of this draft would like to thank the participants of the
        email discussion on this issue.
        Thanks to Bert Greevenbosch, Charles Palmer and
        Carsten Bormann for the detailed reviews and suggestions.
      </t>
    </section>

  </middle>

  <back>
    <references title="Normative References">
      &RFC2119;
      &COAP;
      &BLOCK;
      &LINK-FORMAT;
    </references>
  </back>
</rfc>
    