draft-ietf-core-echo-request-tag: Add in support

Add in support for the Echo and Request-Tag options.

A unique Request-Tag is added to any PUT/POST/FETCH request that contains
a large body.  The server is then able to differentiate between concurrent
sending of large data using the same session.

If a server responds with a 4.01 and Echo option, then the libcoap client
retransmits the request adding in the received option.

If the server responds normally with an Echo option, then the next request
from the client (internally added by libcoap) will contain that Echo option.

It is the responsibility of the server application to add in the Echo
option unless this is triggered by OSCORE.

README.md

@@ -51,6 +51,8 @@ The following RFCs are supported
 
 * RFC8768: Constrained Application Protocol (CoAP) Hop-Limit Option
 
+* draft-ietf-core-echo-request-tag-14: CoAP: Echo, Request-Tag, and Token Processing
+
 There is (D)TLS support for the following libraries
 
 * OpenSSL (Minimum version 1.1.0) [PKI, PSK and PKCS11]

doc/main.md

@@ -36,6 +36,8 @@ The following RFCs are supported
 
 * RFC8768: Constrained Application Protocol (CoAP) Hop-Limit Option
 
+* draft-ietf-core-echo-request-tag-14: CoAP: Echo, Request-Tag, and Token Processing
+
 There is (D)TLS support for the following libraries
 
 * OpenSSL (Minimum version 1.1.0) [PKI, PSK and PKCS11]

include/coap3/block.h

@@ -213,7 +213,7 @@ typedef void (*coap_release_large_data_t)(coap_session_t *session,
  * Used for a client request.
  *
  * If the data spans multiple PDUs, then the data will get transmitted using
- * BLOCK1 option with the addition of the SIZE1 option.
+ * BLOCK1 option with the addition of the SIZE1 and RTAG options.
  * The underlying library will handle the transmission of the individual blocks.
  * Once the body of data has been transmitted (or a failure occurred), then
  * @p release_func (if not NULL) will get called so the application can

include/coap3/coap_block_internal.h

@@ -189,7 +189,8 @@ int coap_handle_request_put_block(coap_context_t *context,
 #endif /* COAP_SERVER_SUPPORT */
 
 #if COAP_CLIENT_SUPPORT
-int coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *rcvd);
+int coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *sent,
+                                    coap_pdu_t *rcvd);
 
 int coap_handle_response_get_block(coap_context_t *context,
                                    coap_session_t *session,

include/coap3/coap_session_internal.h

@@ -133,7 +133,9 @@ struct coap_session_t {
   int dtls_event;                       /**< Tracking any (D)TLS events on this
                                              sesison */
   uint8_t block_mode;             /**< Zero or more COAP_BLOCK_ or'd options */
+  uint32_t tx_rtag;               /**< Next Request-Tag number to use */
   uint64_t tx_token;              /**< Next token number to use */
+  coap_bin_const_t *echo;         /**< Echo value to send with next request */
 };
 
 #if COAP_SERVER_SUPPORT

include/coap3/pdu.h

@@ -130,6 +130,10 @@ typedef enum coap_request_t {
 #define COAP_OPTION_SIZE1          60 /* __N_E_U, uint,      0-4 B, RFC7252 */
 #define COAP_OPTION_NORESPONSE    258 /* _U-_E_U, uint,      0-1 B, RFC7967 */
 
+/* selected option types from draft-ietf-core-echo-request-tag */
+#define COAP_OPTION_ECHO          252 /* _N__E_U, opaque,   0-40 B, RFC???? */
+#define COAP_OPTION_RTAG          292 /* ___RE_U, opaque,    0-8 B, RFC???? */
+
 #define COAP_MAX_OPT            65535 /**< the highest option number we know */
 
 /* CoAP result codes (HTTP-Code / 100 * 40 + HTTP-Code % 100) */

man/coap.txt.in

@@ -68,6 +68,8 @@ See
 
 "RFC8768: Constrained Application Protocol (CoAP) Hop-Limit Option"
 
+"draft-ietf-core-echo-request-tag-14: CoAP: Echo, Request-Tag, and Token Processing"
+
 for further information.
 
 BUGS

man/coap_block.txt.in

@@ -165,7 +165,7 @@ but supports the transmission of data that has a body size that is potentially
 larger than can be fitted into a single client request PDU. The specified
 payload _data_ of length _length_ is associated with the _session_ with the
 first block of data added to the PDU _pdu_ along with the appropriate CoAP
-options such as BLOCK1, and SIZE1 if the data does not fit in
+options such as BLOCK1, SIZE1 and RTAG if the data does not fit in
 a single PDU.  When the block has been acknowledged by the peer, the library
 will then send the next block of data until all the data has been transmitted.
 This function must only be called once per _pdu_.  The _data_ passed to the

man/coap_pdu_setup.txt.in

@@ -301,7 +301,9 @@ COAP_OPTION_SIZE2          28 /* __N_E_U, uint,      0-4 B, RFC7959 */
 COAP_OPTION_PROXY_URI      35 /* CU-___U, String, 1-1034 B, RFC7252 */
 COAP_OPTION_PROXY_SCHEME   39 /* CU-___U, String,  1-255 B, RFC7252 */
 COAP_OPTION_SIZE1          60 /* __N_E_U, uint,      0-4 B, RFC7252 */
+COAP_OPTION_ECHO          252 /* _N__E_U, opaque,   0-40 B, RFC???? */
 COAP_OPTION_NORESPONSE    258 /* _U-_E_U, uint,      0-1 B, RFC7967 */
+COAP_OPTION_RTAG          292 /* ___RE_U, opaque,    0-8 B, RFC???? */
 ----
 See FURTHER INFORMATION as to how to get the latest list.
 

src/block.c

@@ -407,6 +407,8 @@ coap_add_data_large_internal(coap_session_t *session,
   }
 
   avail = pdu->max_size - pdu->used_size - pdu->hdr_size;
+  /* There may be a response with Echo option */
+  avail -= coap_opt_encode_size(COAP_OPTION_ECHO, 40);
   /* May need token of length 8, so account for this */
   avail -= (pdu->token_length < 8) ? 8 - pdu->token_length : 0;
   blk_size = coap_flsll((long long)avail) - 4 - 1;
@@ -490,6 +492,11 @@ coap_add_data_large_internal(coap_session_t *session,
                          coap_encode_var_safe(buf, sizeof(buf),
                                               (unsigned int)length),
                          buf);
+      coap_update_option(pdu,
+                         COAP_OPTION_RTAG,
+                         coap_encode_var_safe8(buf, sizeof(buf),
+                                               ++session->tx_rtag),
+                         buf);
     }
     else {
       /*
@@ -557,6 +564,8 @@ coap_add_data_large_internal(coap_session_t *session,
 
     /* Check we still have space after adding in some options */
     avail = pdu->max_size - pdu->used_size - pdu->hdr_size;
+    /* There may be a response with Echo option */
+    avail -= coap_opt_encode_size(COAP_OPTION_ECHO, 40);
     /* May need token of length 8, so account for this */
     avail -= (pdu->token_length < 8) ? 8 - pdu->token_length : 0;
     if (avail < (ssize_t)chunk) {
@@ -1297,12 +1306,24 @@ coap_handle_request_put_block(coap_context_t *context,
     uint16_t fmt = fmt_opt ? coap_decode_var_bytes(coap_opt_value(fmt_opt),
                                         coap_opt_length(fmt_opt)) :
                              COAP_MEDIATYPE_TEXT_PLAIN;
+    coap_opt_t *rtag_opt = coap_check_option(pdu,
+                                             COAP_OPTION_RTAG,
+                                             &opt_iter);
+    size_t rtag_length = rtag_opt ? coap_opt_length(rtag_opt) : 0;
+    const uint8_t *rtag = rtag_opt ? coap_opt_value(rtag_opt) : NULL;
 
     total = size_opt ? coap_decode_var_bytes(coap_opt_value(size_opt),
                                         coap_opt_length(size_opt)) : 0;
     offset = block.num << (block.szx + 4);
 
     LL_FOREACH(session->lg_srcv, p) {
+      if (rtag_opt || p->rtag_set == 1) {
+        if (!(rtag_opt && p->rtag_set == 1))
+          continue;
+        if (p->rtag_length != rtag_length ||
+            memcmp(p->rtag, rtag, rtag_length) != 0)
+          continue;
+      }
       if (resource == p->resource) {
         break;
       }
@@ -1344,6 +1365,11 @@ coap_handle_request_put_block(coap_context_t *context,
         memcpy(p->observe, coap_opt_value(observe), p->observe_length);
         p->observe_set = 1;
       }
+      if (rtag_opt) {
+        p->rtag_length = (uint8_t)rtag_length;
+        memcpy(p->rtag, rtag, rtag_length);
+        p->rtag_set = 1;
+      }
       p->body_data = NULL;
       LL_PREPEND(session->lg_srcv, p);
     }
@@ -1479,6 +1505,94 @@ coap_handle_request_put_block(coap_context_t *context,
 #endif /* COAP_SERVER_SUPPORT */
 
 #if COAP_CLIENT_SUPPORT
+static int
+check_freshness(coap_session_t *session, coap_pdu_t *rcvd, coap_pdu_t *sent,
+                coap_lg_xmit_t *lg_xmit, coap_lg_crcv_t *lg_crcv)
+{
+  /* Check for ECHO option for freshness */
+  coap_opt_iterator_t opt_iter;
+  coap_opt_t *opt = coap_check_option(rcvd, COAP_OPTION_ECHO, &opt_iter);
+
+  if (opt) {
+    if (sent || lg_xmit || lg_crcv) {
+      /* Need to retransmit original request with ECHO added */
+      coap_pdu_t *echo_pdu;
+      coap_mid_t mid;
+      const uint8_t *data;
+      size_t data_len;
+      int have_data = 0;
+      uint8_t ltoken[8];
+      size_t ltoken_len;
+      uint64_t token;
+
+      if (sent) {
+        if (coap_get_data(sent, &data_len, &data))
+          have_data = 1;
+      }
+      else if (lg_xmit) {
+        sent = &lg_xmit->pdu;
+        if (lg_xmit->length) {
+          size_t blk_size = (size_t)1 << (lg_xmit->blk_size + 4);
+          size_t offset = (lg_xmit->last_block + 1) * blk_size;
+          have_data = 1;
+          data = &lg_xmit->data[offset];
+          data_len = (lg_xmit->length - offset) > blk_size ? blk_size :
+                                                   lg_xmit->length - offset;
+        }
+      }
+      else /* lg_crcv */ {
+        sent = &lg_crcv->pdu;
+        if (coap_get_data(sent, &data_len, &data))
+          have_data = 1;
+      }
+      if (lg_xmit) {
+        token = STATE_TOKEN_FULL(lg_xmit->b.b1.state_token,
+                                 ++lg_xmit->b.b1.count);
+      }
+      else {
+        token = STATE_TOKEN_FULL(lg_crcv->state_token,
+                                 ++lg_crcv->retry_counter);
+      }
+      ltoken_len = coap_encode_var_safe8(ltoken, sizeof(token), token);
+      echo_pdu = coap_pdu_duplicate(sent, session, ltoken_len, ltoken, NULL);
+      if (!echo_pdu)
+        return 0;
+      if (!coap_insert_option(echo_pdu, COAP_OPTION_ECHO,
+                              coap_opt_length(opt), coap_opt_value(opt)))
+        goto no_sent;
+      if (have_data) {
+        coap_add_data(echo_pdu, data_len, data);
+      }
+
+      mid = coap_send_internal(session, echo_pdu);
+      if (mid == COAP_INVALID_MID)
+        goto no_sent;
+      return 1;
+    }
+    else {
+      /* Need to save ECHO value to add to next reansmission */
+no_sent:
+      coap_delete_bin_const(session->echo);
+      session->echo = coap_new_bin_const(coap_opt_value(opt),
+                                         coap_opt_length(opt));
+    }
+  }
+  return 0;
+}
+
+static void
+track_echo(coap_session_t *session, coap_pdu_t *rcvd)
+{
+  coap_opt_iterator_t opt_iter;
+  coap_opt_t *opt = coap_check_option(rcvd, COAP_OPTION_ECHO, &opt_iter);
+
+  if (opt) {
+    coap_delete_bin_const(session->echo);
+    session->echo = coap_new_bin_const(coap_opt_value(opt),
+                                         coap_opt_length(opt));
+  }
+}
+
 /*
  * Need to see if this is a response to a large body request transfer. If so,
  * need to initiate the request containing the next block and not trouble the
@@ -1494,7 +1608,9 @@ coap_handle_request_put_block(coap_context_t *context,
  *         1 Do not call application handler - just send the built response
  */
 int
-coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *rcvd) {
+coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *sent,
+                                coap_pdu_t *rcvd)
+{
   coap_lg_xmit_t *p;
   coap_lg_xmit_t *q;
   uint64_t token_match = STATE_TOKEN_BASE(coap_decode_var_bytes8(rcvd->token,
@@ -1538,6 +1654,7 @@ coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *rcvd) {
              (p->offset + chunk) % ((size_t)1 << (block.szx + 4)));
         }
       }
+      track_echo(session, rcvd);
       if (p->last_block == (int)block.num) {
         /*
          * Duplicate BLOCK ACK
@@ -1583,6 +1700,10 @@ coap_handle_response_send_block(coap_session_t *session, coap_pdu_t *rcvd) {
         return 1;
       }
     }
+    else if (rcvd->code == COAP_RESPONSE_CODE(401)) {
+      if (check_freshness(session, rcvd, sent, p, NULL))
+        return 1;
+    }
 fail_body:
     if (session->lg_crcv) {
       LL_FOREACH(session->lg_crcv, lg_crcv) {
@@ -1673,10 +1794,11 @@ coap_block_build_body(coap_binary_t *body_data, size_t length,
  */
 int
 coap_handle_response_get_block(coap_context_t *context,
-                        coap_session_t *session,
-                        coap_pdu_t *sent,
-                        coap_pdu_t *rcvd,
-                        coap_recurse_t recursive) {
+                               coap_session_t *session,
+                               coap_pdu_t *sent,
+                               coap_pdu_t *rcvd,
+                               coap_recurse_t recursive)
+{
   coap_lg_crcv_t *p;
   int app_has_response = 0;
   coap_block_t block = {0, 0, 0};
@@ -1716,6 +1838,7 @@ coap_handle_response_get_block(coap_context_t *context,
         have_block = 1;
         block_opt = COAP_OPTION_BLOCK2;
       }
+      track_echo(session, rcvd);
       if (have_block) {
         coap_opt_t *fmt_opt = coap_check_option(rcvd,
                                             COAP_OPTION_CONTENT_FORMAT,
@@ -1952,6 +2075,11 @@ coap_handle_response_get_block(coap_context_t *context,
         }
       }
     }
+    else if (rcvd->code == COAP_RESPONSE_CODE(401)) {
+      if (check_freshness(session, rcvd, sent, NULL, p))
+        goto skip_app_handler;
+      goto fail_resp;
+    }
     if (!block.m && !p->observe_set) {
 fail_resp:
       /* lg_crcv no longer required - cache it */
@@ -2002,6 +2130,16 @@ coap_handle_response_get_block(coap_context_t *context,
           coap_block_delete_lg_crcv(session, lg_crcv);
         }
       }
+      track_echo(session, rcvd);
+    }
+    else if (rcvd->code == COAP_RESPONSE_CODE(401)) {
+      coap_lg_crcv_t *lg_crcv = coap_block_new_lg_crcv(session, sent);
+
+      if (lg_crcv) {
+        LL_PREPEND(session->lg_crcv, lg_crcv);
+        return coap_handle_response_get_block(context, session, sent, rcvd,
+                                              COAP_RECURSE_NO);
+      }
     }
   }
   return app_has_response;

src/coap_debug.c

@@ -356,12 +356,14 @@ msg_option_string(uint8_t code, uint16_t option_type) {
     { COAP_OPTION_PROXY_URI, "Proxy-Uri" },
     { COAP_OPTION_PROXY_SCHEME, "Proxy-Scheme" },
     { COAP_OPTION_SIZE1, "Size1" },
-    { COAP_OPTION_NORESPONSE, "No-Response" }
+    { COAP_OPTION_ECHO, "Echo" },
+    { COAP_OPTION_NORESPONSE, "No-Response" },
+    { COAP_OPTION_RTAG, "RTag" }
   };
 
   static struct option_desc_t options_csm[] = {
     { COAP_SIGNALING_OPTION_MAX_MESSAGE_SIZE, "Max-Message-Size" },
-    { COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER, "Block-wise-Transfer" }
+    { COAP_SIGNALING_OPTION_BLOCK_WISE_TRANSFER, "Block-Wise-Transfer" }
   };
 
   static struct option_desc_t options_pingpong[] = {
@@ -634,6 +636,9 @@ coap_show_pdu(coap_log_t level, const coap_pdu_t *pdu) {
 
     case COAP_OPTION_IF_MATCH:
     case COAP_OPTION_ETAG:
+    case COAP_OPTION_ECHO:
+    case COAP_OPTION_NORESPONSE:
+    case COAP_OPTION_RTAG:
       opt_len = coap_opt_length(option);
       opt_val = coap_opt_value(option);
       snprintf((char *)buf, sizeof(buf), "0x");
@@ -856,7 +861,7 @@ char *coap_string_tls_support(char *buffer, size_t bufsize)
   if (have_dtls == 0 && have_tls == 0) {
     snprintf(buffer, bufsize, "(No DTLS or TLS support)");
     return buffer;
-  } 
+  }
   switch (tls_version->type) {
   case COAP_TLS_LIBRARY_NOTLS:
     snprintf(buffer, bufsize, "(No DTLS or TLS support)");

src/coap_session.c

@@ -160,8 +160,9 @@ coap_make_session(coap_proto_t proto, coap_session_type_t type,
   session->dtls_event = -1;
   session->last_ping_mid = COAP_INVALID_MID;
 
-  /* initialize message id */
+  /* Randomly initialize */
   coap_prng((unsigned char *)&session->tx_mid, sizeof(session->tx_mid));
+  coap_prng((unsigned char *)&session->tx_rtag, sizeof(session->tx_rtag));
 
   return session;
 }