[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02

core                                                               K. Li
Internet-Draft                                                   L. Tian
Intended status: Standards Track                                B. Leiba
Expires: April 23, 2012                              Huawei Technologies
                                                        October 21, 2011


                      CoAP Option Extension : Size
                   draft-li-core-coap-size-option-02

Abstract

   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.

Note

   Discussion and suggestions for improvement are requested, and should
   be sent to core@ietf.org.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on April 23, 2012.

Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect



Li, et al.               Expires April 23, 2012                 [Page 1]


Internet-Draft              CoAP-Size-Option                October 2011


   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 3
     1.1.  Justification . . . . . . . . . . . . . . . . . . . . . . . 3
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . 4
   2.  Size Option Extension . . . . . . . . . . . . . . . . . . . . . 4
     2.1.  Size Option Definition  . . . . . . . . . . . . . . . . . . 4
     2.2.  Using the Size Option . . . . . . . . . . . . . . . . . . . 4
   3.  Interaction with Block option . . . . . . . . . . . . . . . . . 5
     3.1.  Usage in POST/PUT Request . . . . . . . . . . . . . . . . . 5
     3.2.  Usage in GET Response . . . . . . . . . . . . . . . . . . . 5
   4.  How to merge into Block draft . . . . . . . . . . . . . . . . . 5
     4.1.  The Size option . . . . . . . . . . . . . . . . . . . . . . 5
     4.2.  Using the Size option . . . . . . . . . . . . . . . . . . . 6
     4.3.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . 6
   5.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
   6.  Security Considerations . . . . . . . . . . . . . . . . . . . . 7
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8
   8.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 8
   9.  Normative References  . . . . . . . . . . . . . . . . . . . . . 8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . . . 8
























Li, et al.               Expires April 23, 2012                 [Page 2]


Internet-Draft              CoAP-Size-Option                October 2011


1.  Introduction

   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.

1.1.  Justification

   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 [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.

   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
   [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.

   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.

   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.

   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.




Li, et al.               Expires April 23, 2012                 [Page 3]


Internet-Draft              CoAP-Size-Option                October 2011


1.2.  Terminology

   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 [RFC2119].


2.  Size Option Extension

2.1.  Size Option Definition


           +------+-----+-------+-----------+--------+---------------+
           | Type | C/E | Name  | Data type | Length | Default       |
           +------+-----+-------+-----------+--------+---------------+
           |  18  |  E  | Size  | uint      | 0-4 B  |               |
           +------+-----+-------+-----------+--------+---------------+

2.2.  Using the Size Option

   The Size Option is used to indicate the size of the resource data
   measured in bytes.

   The GET request including Size=0 is treated as a request to get the
   size of the resource representation (but not the resource payload).

   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.

   The Size option MUST be included in the GET response, if the Size
   option is present in the request.

   Also it SHOULD be used in a POST/PUT request in the first Block
   Option message.

   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.

   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.

   If the Size option is specified it SHOULD be accurate at that time,
   and SHOULD NOT be an estimate.




Li, et al.               Expires April 23, 2012                 [Page 4]


Internet-Draft              CoAP-Size-Option                October 2011


   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.

   This option is "Elective".  It MUST NOT occur more than once.


3.  Interaction with Block option

3.1.  Usage in POST/PUT Request

   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.

3.2.  Usage in GET Response

   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.


4.  How to merge into Block draft

   This section introduces how to merge the Size option draft into Block
   draft with the minimum functionalities.

4.1.  The Size option

   This section will work as section 2.3 in Block draft.








Li, et al.               Expires April 23, 2012                 [Page 5]


Internet-Draft              CoAP-Size-Option                October 2011


           +------+-----+-------+-----------+--------+---------------+
           | Type | C/E | Name  | Data type | Length | Default       |
           +------+-----+-------+-----------+--------+---------------+
           |  18  |  E  | Size  | uint      | 1-4 B  |               |
           +------+-----+-------+-----------+--------+---------------+

4.2.  Using the Size option

   This section will work as section 2.4 in Block draft.

   The Size Option is used to indicate the size of the resource data
   measured in bytes.

   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.

   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.

   If the Size option is specified, it SHOULD be accurate at that time,
   and SHOULD NOT be an estimate.

   The option is "Elective".  It MUST NOT occur more than once.

4.3.  Example

   Example as indicated as Figure 2 in this draft can be added in
   section 3 in the Block draft.


5.  Examples

   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.

   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.



Li, et al.               Expires April 23, 2012                 [Page 6]


Internet-Draft              CoAP-Size-Option                October 2011


      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

   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.

      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


6.  Security Considerations

   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.

   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.

   The latter attack is similar to an attack where the attacker blocks



Li, et al.               Expires April 23, 2012                 [Page 7]


Internet-Draft              CoAP-Size-Option                October 2011


   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.


7.  IANA Considerations

   The IANA is requested to add the following Option Number entry.

                   +--------+---------------+----------------+
                   | Number | Name          | Reference      |
                   +--------+---------------+----------------+
                   |  18    | Size          | Section 2      |
                   +--------+---------------+----------------+


8.  Acknowledgements

   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.


9.  Normative References

   [I-D.ietf-core-block]
              Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
              draft-ietf-core-block-04 (work in progress), July 2011.

   [I-D.ietf-core-coap]
              Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
              "Constrained Application Protocol (CoAP)",
              draft-ietf-core-coap-07 (work in progress), July 2011.

   [I-D.ietf-core-link-format]
              Shelby, Z., "CoRE Link Format",
              draft-ietf-core-link-format-07 (work in progress),
              July 2011.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.








Li, et al.               Expires April 23, 2012                 [Page 8]


Internet-Draft              CoAP-Size-Option                October 2011


Authors' Addresses

   Kepeng Li
   Huawei Technologies
   Huawei Base, Bantian, Longgang District
   Shenzhen, Guangdong  518129
   P. R. China

   Phone: +86-755-28974289
   Email: likepeng@huawei.com


   Linyi Tian
   Huawei Technologies
   Huawei Base, Bantian, Longgang District
   Shenzhen, Guangdong  518129
   P. R. China

   Phone: +86-755-28978078
   Email: tianlinyi@huawei.com


   Barry Leiba
   Huawei Technologies

   Phone: +1 646 827 0648
   Email: barryleiba@computer.org
   URI:   http://internetmessagingtechnology.org/























Li, et al.               Expires April 23, 2012                 [Page 9]


Html markup produced by rfcmarkup 1.127, available from https://tools.ietf.org/tools/rfcmarkup/