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

Versions: 00 01 02 draft-ietf-core-coap-tcp-tls

CORE                                                     C. Bormann, Ed.
Internet-Draft
Intended status: Standards Track                 Universitaet Bremen TZI
Expires: December 29, 2016                                 June 27, 2016


                        CoAP Signaling Messages
                   draft-bormann-core-coap-sig-02

Abstract

   draft-ietf-core-coap-tcp-tls defines how to transport CoAP messages
   on reliable transports such as TCP, TLS, or WebSockets.

   All these underlying protocols have ways to set up connection
   properties and manage the connection.  In many cases, these ways
   cannot be used very well for managing CoAP's use of the connection.

   Signaling messages are a way to signal information that is about the
   connection.  They form a third basic kind of messages in CoAP, beyond
   requests and responses.  Message class 7 is used for signaling
   messages.

   Signaling messages are only relevant for the connection they appear
   in.  The present draft assumes reliable, sequence-preserving
   connections.  It is for further study whether signaling messages are
   needed or useful for DTLS connections.

   The present draft, when adopted, would resolve CoRE tickets #400
   (message sizes), #388 (by providing a foundation for a mechanism for
   version negotiation, once that is needed), #390 (connection close
   reason), #391 (server name indication), #394 (ping/pong).

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




Bormann                 Expires December 29, 2016               [Page 1]


Internet-Draft           CoAP Signaling Messages               June 2016


   This Internet-Draft will expire on December 29, 2016.

Copyright Notice

   Copyright (c) 2016 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
   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  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Signaling messages  . . . . . . . . . . . . . . . . . . . . .   3
   4.  Capability and Settings Messages  . . . . . . . . . . . . . .   4
     4.1.  Server-Name Setting Option  . . . . . . . . . . . . . . .   4
     4.2.  Max-Message-Size Capability Indication Option . . . . . .   5
     4.3.  Block-wise-Transfer Capability Indication Option  . . . .   5
     4.4.  Using the Capability and Settings message for version
           negotiation . . . . . . . . . . . . . . . . . . . . . . .   6
   5.  Ping and Pong Messages  . . . . . . . . . . . . . . . . . . .   6
     5.1.  Custody Option  . . . . . . . . . . . . . . . . . . . . .   6
   6.  Release Messages  . . . . . . . . . . . . . . . . . . . . . .   7
   7.  Abort Messages  . . . . . . . . . . . . . . . . . . . . . . .   8
   8.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   9
   9.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   10. IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
     10.1.  Message Codes  . . . . . . . . . . . . . . . . . . . . .  10
     10.2.  Signaling Options  . . . . . . . . . . . . . . . . . . .  11
   11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  12
     11.1.  Normative References . . . . . . . . . . . . . . . . . .  12
     11.2.  Informative References . . . . . . . . . . . . . . . . .  12
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  12
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  12

1.  Introduction

   (Please see abstract for now.)





Bormann                 Expires December 29, 2016               [Page 2]


Internet-Draft           CoAP Signaling Messages               June 2016


2.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in
   [RFC2119].

   The definitions of [RFC7252] apply.

   In this document, the term "byte" is used in its now customary sense
   as a synonym for "octet".

   Where bit arithmetic is explained, this document uses the notation
   familiar from the programming language C, except that the operator
   "**" stands for exponentiation.

3.  Signaling messages

   Signaling messages are structured like any other CoAP message; they
   have a code, a token, options, and optionally a payload.  (See
   Section 3 of [RFC7252] for the overall structure, as adapted to the
   specific transport.)  The code for a signaling message comes from the
   7.xx space.

   Option numbers for signaling messages are specific to the message
   code, i.e., they do not share the number space with CoAP options for
   request/response messages or with signaling messages using other
   codes.

   Signaling options can be elective or critical (see Section 5.4.1 of
   [RFC7252]); if a signaling message option is critical and not
   understood by the receiver, it MUST abort the connection (see
   Section 7.  (If the option is understood but somehow cannot be
   carried out, the option defines how to handle the situation.)

   Payloads in signaling messages are diagnostic payloads (see
   Section 5.5.2 of [RFC7252]), unless otherwise determined by a
   signaling message option.

   This specification lays out five kinds of signaling messages, without
   necessarily defining an instance of each of the kinds.

   For each message, there is an emitter (that sends the message) and a
   peer receiving the message.







Bormann                 Expires December 29, 2016               [Page 3]


Internet-Draft           CoAP Signaling Messages               June 2016


4.  Capability and Settings Messages

   Capability and Settings messages are used for two purposes:

   o  Capability indication options indicate a capability of the emitter
      to the receiving peer.  Capability options are generally elective
      options.

   o  Setting options indicate a setting that will be applied by the
      emitter.  Setting options are generally critical options.

   Both capability indication options and setting options are
   cumulative, i.e., a capability message without any option is a no-
   operation (and can be used as such).  (An option that is given might
   override a previous value for the same option; the option defines how
   to handle this, if needed.)  Most CSM options are useful mainly as
   initial messages in the connection.

   Capability and Settings messages carry the code 7.01 (CSM).

                        +------+------+-----------+
                        | Code | Name | Reference |
                        +------+------+-----------+
                        | 7.01 | CSM  | [RFCthis] |
                        +------+------+-----------+

   A number of options for Capability and Settings messages are defined
   in the following subsections.

4.1.  Server-Name Setting Option

   A client can indicate a default value that it wants to set for the
   Uri-Host options in the messages it sends to the server:

   The Server-Name option is defined as follows:

         +---------------+------------+-------------+-----------+
         | Option Number | Applies to | Option Name | Reference |
         +---------------+------------+-------------+-----------+
         | 1             | CSM        | Server-Name | [RFCthis] |
         +---------------+------------+-------------+-----------+

   The Server-Name option is a critical option (1 is odd) and carries a
   "string" value, with the same restrictions as for Uri-Host
   (Section 5.10 of RFC 7252: length is between 1 and 255).






Bormann                 Expires December 29, 2016               [Page 4]


Internet-Draft           CoAP Signaling Messages               June 2016


   For TLS, the initial value for the Server-Name option is given by the
   SNI value.  SECURITY CONSIDERATIONS.  For Websockets, the initial
   value for the Server-Name is given by the HTTP Host header field.

4.2.  Max-Message-Size Capability Indication Option

   An emitter can indicate a maximum message size that it can
   comfortably operate on as a recipient.

   The Max-Message-Size option is defined as follows:

       +---------------+------------+------------------+-----------+
       | Option Number | Applies to | Option Name      | Reference |
       +---------------+------------+------------------+-----------+
       | 2             | CSM        | Max-Message-Size | [RFCthis] |
       +---------------+------------+------------------+-----------+

   The Max-Message-Size option is an elective option (2 is even) and
   carries a "uint" value, indicating the message size in bytes.  As per
   Section 4.6 of [RFC7252], the default value (and the value used when
   this Option is not implemented) is 1152.  (Note that a peer
   implementation that relies on this option being indicated and having
   a certain minimum value will enjoy only limited interoperability.)

4.3.  Block-wise-Transfer Capability Indication Option

   An emitter can indicate that it supports the block-wise transfer
   protocol defined in [I-D.ietf-core-block].

   The Block-wise-Transfer option is defined as follows:

     +---------------+------------+---------------------+-----------+
     | Option Number | Applies to | Option Name         | Reference |
     +---------------+------------+---------------------+-----------+
     | 4             | CSM        | Block-wise-Transfer | [RFCthis] |
     +---------------+------------+---------------------+-----------+

   The Block-wise-Transfer option is an elective option (4 is even) and
   carries an "empty" value.  If the option is not given, the peer has
   no information about whether block-wise transfers are supported by
   the emitter or not.  An implementation that supports block-wise
   transfers SHOULD indicate the Block-Wise Transfer option.  If a Max-
   Message-Size option is being indicated (in the same of a different
   CSM message) with a value that is greater than 1152, the Block-Wise
   Transfer option also indicates support for BERT
   [I-D.ietf-core-coap-tcp-tls].





Bormann                 Expires December 29, 2016               [Page 5]


Internet-Draft           CoAP Signaling Messages               June 2016


4.4.  Using the Capability and Settings message for version negotiation

   CoAP is defined in RFC 7252 with a version number of 1.  In contrast
   to the message layer for UDP and DTLS, the CoAP over TCP message
   layer does not send the version number in each single message.
   Instead, options for the Capability and Settings message can be used
   to perform a version negotiation.

   At the time of writing, there is no known reason for supporting
   version numbers different from 1.  The details of a version
   negotiation, once it is actually needed, will depend on the specifics
   of the new version(s), so the present specification makes no attempt
   to specify these details.  However, Capability and Settings messages
   have been specifically designed with a view to supporting such a
   potential future need.

5.  Ping and Pong Messages

   NOTE: The present specification assumes that the CoAP over TCP
   specification [I-D.ietf-core-coap-tcp-tls] specifies that empty
   messages ([RFC7252]) can always be sent and will be ignored.  This
   provides for a basic keep-alive function that can, e.g., refresh NAT
   bindings.  In contrast, Ping and Pong messages are a bidirectional
   exchange.

   A Ping message is responded to by a single Pong message with the same
   token.  As with all signaling messages, the recipient of a Ping or
   Pong message MUST ignore elective options it does not understand.

   Ping and Pong messages carry the code 7.02 (Ping) and 7.03 (Pong),
   respectively.

                        +------+------+-----------+
                        | Code | Name | Reference |
                        +------+------+-----------+
                        | 7.02 | Ping | [RFCthis] |
                        |      |      |           |
                        | 7.03 | Pong | [RFCthis] |
                        +------+------+-----------+

5.1.  Custody Option

   A peer replying to a Ping message can add a Custody Option to the
   Pong message it returns.  The Option indicates that the application
   has processed all request/response messages that it has received in
   the present connection ahead of the Ping message that prompted the
   Pong message.  (Note that there is no definition of specific
   application semantics of "processed", but there is an expectation



Bormann                 Expires December 29, 2016               [Page 6]


Internet-Draft           CoAP Signaling Messages               June 2016


   that the emitter of the Ping leading to the Pong with a Custody
   Option should be able to free buffers based on this indication.)

   A Custody Option can also be sent in a Ping message to explicitly
   request the return of a Custody Option in the Pong message.  A peer
   is, however, always free to indicate that it has finished processing
   all previous request/response messages by sending a Custody Option
   (which is therefore elective) in a Pong message.  A peer is also free
   NOT to send a Custody Option in case it is still processing previous
   request/response messages, however, it SHOULD delay its response to a
   Ping with a Custody Option until it also can return one.

         +---------------+------------+-------------+-----------+
         | Option Number | Applies to | Option Name | Reference |
         +---------------+------------+-------------+-----------+
         | 2             | Ping, Pong | Custody     | [RFCthis] |
         +---------------+------------+-------------+-----------+

   The Custody option is an elective option (2 is even) and carries an
   "empty" value.

6.  Release Messages

   A release message indicates that the emitter does not want to
   continue maintaining the connection and opts for an orderly shutdown;
   the details are in the options.  A diagnostic payload MAY be
   included.  A release message will normally be replied to by the peer
   by closing the TCP/TLS connection.  Messages may be in flight when
   the emitter decides to send a Release message; the general
   expectation is that these will still be processed.

   Release messages carry the code 7.04 (Release).

                      +------+---------+-----------+
                      | Code | Name    | Reference |
                      +------+---------+-----------+
                      | 7.04 | Release | [RFCthis] |
                      +------+---------+-----------+

   Release messages can indicate one or more reasons using elective
   options; the following options are defined:










Bormann                 Expires December 29, 2016               [Page 7]


Internet-Draft           CoAP Signaling Messages               June 2016


     +---------------+------------+---------------------+-----------+
     | Option Number | Applies to | Option Name         | Reference |
     +---------------+------------+---------------------+-----------+
     | 2             | Release    | Bad-Server-Name     | [RFCthis] |
     |               |            |                     |           |
     | 4             | Release    | Alternative-Address | [RFCthis] |
     |               |            |                     |           |
     | 6             | Release    | Hold-Off            | [RFCthis] |
     +---------------+------------+---------------------+-----------+

   The Bad-Server-Name option indicates that the default as set by the
   CSM option Server-Name is unlikely to be useful for this server.  The
   value is empty.  (2 is even, i.e., the option is elective.)

   The Alternative-Address option requests the peer to instead open a
   connection of the same kind as the present connection to the
   alternative transport address given.  The value is a string, of the
   form "authority" defined in Section 3.2 of RFC 3986.  (4 is even,
   i.e., the option is elective.)  SECURITY CONSIDERATIONS.

   The Hold-Off option indicates that the server is requesting that the
   peer not reconnect to it for the number of seconds given as the
   value.  The value is a uint.  (6 is even, i.e., the option is
   elective.)

7.  Abort Messages

   An abort message indicates that the emitter is unable to continue
   maintaining the connection and cannot even wait for an orderly
   release; the emitter shuts down the connection immediately after the
   abort (and may or may not wait for a release or abort message or
   connection shutdown in the inverse direction).  A diagnostic payload
   SHOULD be included in the Abort message.  Messages may be in flight
   when the emitter decides to send an abort message; the general
   expectation is that these will NOT be processed.

   Abort messages carry the code 7.05 (Abort).

                       +------+-------+-----------+
                       | Code | Name  | Reference |
                       +------+-------+-----------+
                       | 7.05 | Abort | [RFCthis] |
                       +------+-------+-----------+

   Abort messages can indicate one or more reasons using elective
   options; the following options are defined:





Bormann                 Expires December 29, 2016               [Page 8]


Internet-Draft           CoAP Signaling Messages               June 2016


        +---------------+------------+----------------+-----------+
        | Option Number | Applies to | Option Name    | Reference |
        +---------------+------------+----------------+-----------+
        | 2             | Abort      | Bad-CSM-Option | [RFCthis] |
        +---------------+------------+----------------+-----------+

   The Bad-CSM-Option indicates that the emitter is unable to process
   the CSM option identified by its option number, e.g. when it is
   critical and the option number is unknown by the emitter, or when
   there is parameter problem with the value of an elective option.  The
   value is a uint.  (2 is even, i.e., the option is elective.)  (More
   detailed information SHOULD be given as a diagnostic payload.)

   One reason for an emitter to generate an abort message is a general
   syntax error in the byte stream received; no specific option has been
   defined for this, as the details of that syntax error are best left
   to a diagnostic payload.

8.  Examples

   An encoded example of a Ping message with a non-empty token is shown
   in Figure 1.

       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
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |      0x01     |      0xe2     |      0x42     |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

       Len   =    0 -------> 0x01
       TKL   =    1 ___/
       Code  = 7.02 Ping --> 0xe2
       Token =               0x42

                      Figure 1: Ping Message Example

   An encoded example of the corresponding Pong message is shown in
   Figure 2.













Bormann                 Expires December 29, 2016               [Page 9]


Internet-Draft           CoAP Signaling Messages               June 2016


       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
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |      0x01     |      0xe3     |      0x42     |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

       Len   =    0 -------> 0x01
       TKL   =    1 ___/
       Code  = 7.03 Pong --> 0xe3
       Token =               0x42

                      Figure 2: Pong Message Example

9.  Security Considerations

   The security considerations of [RFC7252] apply.

   o  The guidance given by an Alternative-Address option cannot be
      followed blindly.  In particular, a peer MUST NOT assume that a
      successful connection to the Alternative-Address inherits all the
      security properties of the current connection.

   o  SNI vs. Server-Name: Any security negotiated in the TLS handshake
      is for the SNI name exchanged in the TLS handshake and checked
      against the certificate provided by the server.  The Server-Name
      option cannot be used to extend these security properties to the
      additional server name.

10.  IANA Considerations

10.1.  Message Codes

   IANA is requested to create a third sub-registry for values of the
   Code field in the CoAP header (cf.  Section 12.1 of [RFC7252]).

   The IANA policy for future additions to this sub-registry is "IETF
   Review or IESG Approval" as described in [RFC5226].

   (Editor note to be removed: remember to copy down values from above)












Bormann                 Expires December 29, 2016              [Page 10]


Internet-Draft           CoAP Signaling Messages               June 2016


                      +------+---------+-----------+
                      | Code | Name    | Reference |
                      +------+---------+-----------+
                      | 7.01 | CSM     | [RFCthis] |
                      |      |         |           |
                      | 7.02 | Ping    | [RFCthis] |
                      |      |         |           |
                      | 7.03 | Pong    | [RFCthis] |
                      |      |         |           |
                      | 7.04 | Release | [RFCthis] |
                      |      |         |           |
                      | 7.05 | Abort   | [RFCthis] |
                      +------+---------+-----------+

10.2.  Signaling Options

   IANA is requested to create a sub-registry for signaling options
   similar to the CoAP Option Numbers Registry (Section 12.2 of
   [RFC7252]), with the single change that a fourth column is added to
   the sub-registry that is one of the message codes in the message code
   subregistry (Section 10.1).

   The IANA policy for future additions to this sub-registry is based on
   number ranges for the option numbers, analogous to the policy defined
   in Section 12.2 of [RFC7252].

   (Editor note to be removed: remember to copy down values from above)

     +---------------+------------+---------------------+-----------+
     | Option Number | Applies to | Option Name         | Reference |
     +---------------+------------+---------------------+-----------+
     | 1             | CSM        | Server-Name         | [RFCthis] |
     |               |            |                     |           |
     | 2             | CSM        | Max-Message-Size    | [RFCthis] |
     |               |            |                     |           |
     | 4             | CSM        | Block-wise-Transfer | [RFCthis] |
     |               |            |                     |           |
     | 2             | Ping, Pong | Custody             | [RFCthis] |
     |               |            |                     |           |
     | 2             | Release    | Bad-Server-Name     | [RFCthis] |
     |               |            |                     |           |
     | 4             | Release    | Alternative-Address | [RFCthis] |
     |               |            |                     |           |
     | 6             | Release    | Hold-Off            | [RFCthis] |
     |               |            |                     |           |
     | 2             | Abort      | Bad-CSM-Option      | [RFCthis] |
     +---------------+------------+---------------------+-----------+




Bormann                 Expires December 29, 2016              [Page 11]


Internet-Draft           CoAP Signaling Messages               June 2016


11.  References

11.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              DOI 10.17487/RFC5226, May 2008,
              <http://www.rfc-editor.org/info/rfc5226>.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014,
              <http://www.rfc-editor.org/info/rfc7252>.

11.2.  Informative References

   [I-D.ietf-core-block]
              Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP",
              draft-ietf-core-block-20 (work in progress), April 2016.

   [I-D.ietf-core-coap-tcp-tls]
              Bormann, C., Lemay, S., Technologies, Z., and H.
              Tschofenig, "A TCP and TLS Transport for the Constrained
              Application Protocol (CoAP)", draft-ietf-core-coap-tcp-
              tls-02 (work in progress), April 2016.

Acknowledgements

   Significant parts of the present text have been contributed by Hannes
   Tschofenig.  Matthias Kovatsch contributed significantly to this
   draft.

Authors' Addresses

   Carsten Bormann (editor)
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63921
   Email: cabo@tzi.org




Bormann                 Expires December 29, 2016              [Page 12]


Internet-Draft           CoAP Signaling Messages               June 2016


   Klaus Hartke
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63905
   Email: hartke@tzi.org











































Bormann                 Expires December 29, 2016              [Page 13]


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