CoRE Working Group                                        Z. Shelby, Ed.
Internet-Draft                                                 Sensinode
Intended status: Standards Track                              C. Bormann
Expires: April 21, 2011                          Universitaet Bremen TZI
                                                        October 18, 2010

                      Blockwise transfers in CoAP


   CoAP is a RESTful transfer protocol for constrained nodes and
   networks.  CoAP is based on datagram transport, which limits the
   maximum size of resource representations that can be transferred
   without too much fragmentation.  The Block option provides a minimal
   way to transfer larger representations in a block-wise fashion.

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

   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 21, 2011.

Copyright Notice

   Copyright (c) 2010 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
   ( in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   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

Shelby & Bormann         Expires April 21, 2011                 [Page 1]

Internet-Draft                 CoAP-block                   October 2010

   described in the Simplified BSD License.

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Block-wise transfers . . . . . . . . . . . . . . . . . . . . .  4
     2.1.  The Block Option . . . . . . . . . . . . . . . . . . . . .  4
     2.2.  Using the Block Option . . . . . . . . . . . . . . . . . .  6
   3.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  9
   4.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10
     4.1.  Mitigating Amplification Attacks . . . . . . . . . . . . . 10
   5.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
   6.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 12
     6.1.  Normative References . . . . . . . . . . . . . . . . . . . 12
     6.2.  Informative References . . . . . . . . . . . . . . . . . . 12
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13

Shelby & Bormann         Expires April 21, 2011                 [Page 2]

Internet-Draft                 CoAP-block                   October 2010

1.  Introduction

   The CoRE WG is tasked with standardizing an Application Protocol for
   Constrained Networks/Nodes, CoAP.  This protocol is intended to
   provide RESTful [REST] services not unlike HTTP [RFC2616], while
   reducing the complexity of implementation as well as the size of
   packets exchanged in order to make these services useful in a highly
   constrained network of themselves highly constrained nodes.

   This objective requires restraint in a number of sometimes
   conflicting ways:

   o  reducing implementation complexity in order to minimize code size,

   o  reducing message sizes in order to minimize the number of
      fragments needed for each message (in turn to maximize the
      probability of delivery of the message), the amount of
      transmission power needed and the loading of the limited-bandwidth

   o  reducing requirements on the environment such as stable storage,
      good sources of randomness or user interaction capabilities.

   CoAP is based on datagram transports such as UDP, which limit the
   maximum size of resource representations that can be transferred
   without creating unreasonable levels of fragmentation.  The Block
   option provides a minimal way to transfer larger resource
   representations in a block-wise fashion.

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119]
   and indicate requirement levels for compliant CoAP implementations.

Shelby & Bormann         Expires April 21, 2011                 [Page 3]

Internet-Draft                 CoAP-block                   October 2010

2.  Block-wise transfers

   Not all resource representations will fit into a single link layer
   packet of a constrained network.  Using fragmentation (either at the
   adaptation layer or at the IP layer) to enable the transport of
   larger representations is possible up to the maximum size of the
   underlying datagram protocol (such as UDP), but the fragmentation/
   reassembly process loads the lower layers with conversation state
   that is better managed in the application layer.

   This specification proposes an option to enable _block-wise_ access
   to resource representations.  The overriding objective is to avoid
   creating conversation state at the server for block-wise GET
   requests.  (It is impossible to fully avoid creating conversation
   state for POST/PUT, if the creation/replacement of resources is to be
   atomic; where that property is not needed, there is no need to create
   server conversation state in this case, either.)

   Implementation of the Block option is intended to be optional.
   However, when it is present in a CoAP message, it MUST be processed;
   therefore it is identified as a critical option.

   The size of the blocks should not be fixed by the protocol.  On the
   other hand, implementation should be as simple as possible.  The
   Block option therefore supports a small range of power-of-two block
   sizes, from 2^4 (16) to 2^11 (2048) bytes.  One of these eight values
   can be encoded in three bits (0 for 2^4 to 7 for 2^11 bytes), the
   "SZX" (size exponent); the actual block size is then "1 << (SZX +

2.1.  The Block Option

   When a representation is larger than can be comfortably transferred
   in a single UDP datagram, the Block option can be used to indicate a
   block-wise transfer.  Block is a 1-, 2- or 3-byte integer, the four
   least significant bits of which indicate the size and whether the
   current block-wise transfer is the last block being transferred (M or
   "more" bit).  The value divided by sixteen is the number of the block
   currently being transferred, starting from zero, i.e., the current
   transfer is about the "size" bytes starting at "block number << (SZX
   + 4)".  The default value of the Block Option is zero, indicating
   that the current block is the first (block number 0) and only (M bit
   not set) block of the transfer; however, there is no explicit size
   implied by this default value.

Shelby & Bormann         Expires April 21, 2011                 [Page 4]

Internet-Draft                 CoAP-block                   October 2010

           0 1 2 3 4 5 6 7
          |  NUM  |M| SZX |

           0                   1
           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
          |          NUM          |M| SZX |

           0                   1                   2
           0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
          |                   NUM                 |M| SZX |

                          Figure 1: Block option

   (Note that the option with the last 4 bits masked out, shifted to the
   left by the value of SZX, gives the byte position of the block.)

   NUM:  Block Number.  The block number is a variable 4-20 bit unsigned
      integer indicating the block number being requested or provided.
      Block number 0 indicates the first block of a representation.

   M: More Flag.  This flag indicates if this block is the last in a
      representation when set.  When not set it indicates that there are
      one or more blocks available.  When the block option is used to
      retrieve a specific block number the M bit MUST be sent as zero
      and ignored on reception.

   SZX:  Block Size.  The block size indicates the size of a block to
      the power of two.  Thus block size = 2^(SZX + 4).  Thus the
      minimum block size is 16 and the maximum is 2048.

   The Block option is used in one of three roles:

   o  In the request for a GET, the Block option gives the block number
      requested and suggests a block size (block number 0) or echoes the
      block size of previous blocks received (block numbers other than

   o  In the response for a GET or in the request for a PUT or POST, the
      Block option describes what block number is contained in the
      payload, and whether further blocks are part of that body (M bit).
      If the M bit is set, the size of the payload body in bytes MUST

Shelby & Bormann         Expires April 21, 2011                 [Page 5]

Internet-Draft                 CoAP-block                   October 2010

      indeed be the power of two given by the block size.  All blocks
      for a REST transaction MUST use the same block size, except for
      the last block (M bit not set).

   o  In the response for a PUT or POST, the Block option indicates what
      block number is being acknowledged.  In this case, the M bit is
      set to indicate that this response does not carry the final
      response to the request; this can occur when the M bit was set in
      the request and the server implements PUT/POST atomically (i.e.,
      acts only upon reception of the last block).

2.2.  Using the Block Option

   Using the Block option, a single REST operation can be split into
   multiple CoAP message transactions.  Each of these message
   transactions uses their own CoAP transaction ID.

   When a GET is answered with a response carrying a Block option with
   the M bit set, the requestor may retrieve additional blocks of the
   resource representation by sending requests with a Block option
   giving the block number desired.  In such a Block option, the M bit
   MUST be sent as zero and ignored on reception.

   To influence the block size used in response to a GET request, the
   requestor uses the Block option, giving the desired size, a block
   number of zero and an M bit of zero.  A server SHOULD use the block
   size indicated or a smaller size.  Any further block-wise requests
   for blocks beyond the first one MUST indicate the same block size
   that was already used in the response for the first one.

   If the Block option is used by the requestor, all GET requests in a
   single transaction (except for the last one with the M bit not set)
   MUST ultimately use the same size.  The server SHOULD use the block
   size indicated in the request option or a smaller size, but the
   requestor MUST take note of the actual block size used in the
   response it receives to its initial GET and proceed to use it in
   subsequent GETs; the server behavior MUST ensure that this client
   behavior results in the same block size for all responses in a
   sequence (except for the last one with the M bit not set).

   Block-wise transfers can be used to GET resources the representations
   of which are entirely static (not changing over time at all, such as
   in a schema describing a device), or for dynamically changing
   resources.  In the latter case, the Block option SHOULD be used in
   conjunction with the Etag option, to ensure that the blocks being
   reassembled are from the same version of the representation.  When
   reassembling the representation from the blocks being exchanged, the
   reassembler MUST compare Etag options.  If the Etag options do not

Shelby & Bormann         Expires April 21, 2011                 [Page 6]

Internet-Draft                 CoAP-block                   October 2010

   match in a GET transfer, the requestor has the option of attempting
   to retrieve fresh values for the blocks it retrieved first.  To
   minimize the resulting inefficiency, the server MAY cache the current
   value of a representation for an ongoing sequence of requests, but
   there is no requirement for the server to establish any state.  The
   client MAY facilitate identifying the sequence by using the Token

   In a PUT or POST transfer, the Block option refers to the body in the
   request, i.e., there is no way to perform a block-wise retrieval of
   the body of the response.  Servers that do need to supply large
   bodies in response to PUT/POST SHOULD therefore be employing

   In a PUT or POST transfer that is intended to be implemented in an
   atomic fashion at the server, the actual creation/replacement takes
   place at the time a block with the M bit unset is received.  If not
   all previous blocks are available at the server at this time, the
   transfer fails and error code 4__ (TBD) MUST be returned.  The error
   code 4__ can also be returned at any time by a server that does not
   currently have the resources to store blocks for a block-wise PUT or
   POST transfer that it would intend to implement in an atomic fashion.

   If multiple concurrently proceeding block-wise PUT or POST operations
   are possible, the requestor SHOULD use the Token option to clearly
   separate the different sequences.  In this case, when reassembling
   the representation from the blocks being exchanged to enable atomic
   processing, the reassembler MUST compare any Token options present
   (taking an absent Token option to default to the empty Token).  If
   atomic processing is not desired, there is no need to check the Token

   In summary, this specification:  Adds a Block Option that can be used
      for block-wise transfers.

   Benefits:  Transfers larger than can be accommodated in constrained-
      network link-layer packets can be performed in smaller blocks.

      No hard-to-manage conversation state is created at the adaptation
      layer or IP layer for fragmentation.

      The transfer of each block is acknowledged, enabling
      retransmission if required.

      Both sides have a say in the block size that actually will be

Shelby & Bormann         Expires April 21, 2011                 [Page 7]

Internet-Draft                 CoAP-block                   October 2010

   TBD:  Give examples with detailed message flows for a block-wise GET,
      PUT and POST.

Shelby & Bormann         Expires April 21, 2011                 [Page 8]

Internet-Draft                 CoAP-block                   October 2010

3.  IANA Considerations

   This draft adds the following option number to Table 2 of

   | Type | C/E | Name  | Data type      | Length | Default            |
   |   13 | C   | Block | Unsigned       | 1-3 B  | 0 (see             |
   |      |     |       | Integer        |        | Section 2.1)       |

Shelby & Bormann         Expires April 21, 2011                 [Page 9]

Internet-Draft                 CoAP-block                   October 2010

4.  Security Considerations

   TBD.  (Weigh the security implications of application layer block-
   wise transfer against those of adaptation-layer or IP-layer

4.1.  Mitigating Amplification Attacks

   TBD.  (This section discusses how CoAP nodes could become implicated
   in DoS attacks by using the amplifying properties of the protocol, as
   well as mitigations for this threat.)

   A CoAP server can reduce the amount of amplification it provides to
   an attacker by offering large resource representations only in
   relatively small blocks.  E.g., for a 1000 byte resource, a 10-byte
   request might result in an 80-byte response (with a 64-byte block)
   instead of a 1016-byte response, considerably reducing the
   amplification provided.

Shelby & Bormann         Expires April 21, 2011                [Page 10]

Internet-Draft                 CoAP-block                   October 2010

5.  Acknowledgements

   Of course, much of the content of this draft is the result of
   discussions with the [I-D.ietf-core-coap] authors.  Tokens were
   suggested by Gilman Tolle and refined by Klaus Hartke.

Shelby & Bormann         Expires April 21, 2011                [Page 11]

Internet-Draft                 CoAP-block                   October 2010

6.  References

6.1.  Normative References

              Shelby, Z., Frank, B., and D. Sturek, "Constrained
              Application Protocol (CoAP)", draft-ietf-core-coap-02
              (work in progress), September 2010.

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

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

6.2.  Informative References

   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", 2000.

Shelby & Bormann         Expires April 21, 2011                [Page 12]

Internet-Draft                 CoAP-block                   October 2010

Authors' Addresses

   Zach Shelby (editor)
   Kidekuja 2
   Vuokatti  88600

   Phone: +358407796297

   Carsten Bormann
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359

   Phone: +49-421-218-63921
   Fax:   +49-421-218-7000

Shelby & Bormann         Expires April 21, 2011                [Page 13]